KLARA API documentation

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

98Endpoints

5Domains

RESTover HTTPS

↓ klara-openapi.json98 operations, 759 KB, 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 98 integration endpoints, grouped by domain.

Getting started

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.
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.
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.
Set up authentication
Send the key as an X-API-KEY header, or obtain a bearer token via the token flow. See Authentication.
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.
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.

Superseded	Use 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

Verb	Used for	Endpoints
GET	Retrieving resources	56
PUT	Replacing a resource completely	10
POST	Creating resources, and some actions such as `/send`	25
DELETE	Removing a resource	7

98 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

Header	Value	When
`X-API-KEY`	your API key	API key authentication
`Authorization`	`Bearer <JWT>`	Token authentication
`Accept`	`application/json`	Almost everywhere. Three endpoints return binary or PDF instead, see below
`Content-Type`	depends 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-Language`	`de-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 type	Endpoints	Which ones
`application/json`	22	every endpoint that has one
`application/x-www-form-urlencoded`	4	`POST /core/latest/generic-token` `POST /core/latest/tenants` `POST /core/latest/token` `POST /core/latest/token/by-microsoft`
`multipart/form-data`	3	`POST /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 type	Endpoints	Which ones
`application/json`	98	every endpoint that has one
`application/octet-stream`	2	`GET /core/latest/articles/{article-id}/images/{image-id}` `POST /core/latest/payroll-interface-file`
`application/pdf`	1	`POST /core/v1/invoices/{id}/printed-document`

What an error body contains

The specification declares 447 error responses on 98 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.

Schema	Fields	Error responses	Operations
`ErrorMessage`	`code`, `createdTime`, `detail`, `message`, `uuid`	428	98
`ErrorResponse`	`error`, `error_description`	19	5

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

GET /core/v2/tenants/companies
POST /core/latest/subscriptions
POST /core/latest/tenants
POST /core/v2/tenants/companies
PUT /core/v2/tenants/companies

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 3 error codes of its own, in the code field of the error body:

Code	Status	Meaning	Where
`auth.credentials_missing`	`401`	Neither an Authorization: Bearer header nor an API key header was present on the request.	3 operations
`booking.status_not_allowed`	`400`	bookingStatus was neither BOOKED nor PLANNED.	1 operation
`invoice.id_must_be_zero`	`400`	The request body carried a non-zero id. This operation only creates invoices; use PUT /core/v1/invoices to modify an existing one.	1 operation

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.

Mechanism	How	Best for
`apiKeyAuth`	Header `X-API-KEY`	Server-to-server integrations bound to one company
`bearerAuth`	Header `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.

Endpoint	`grant_type`	Required fields	Returns
`POST /core/latest/token`	`password`	`username`, `password`, `tenant_id`, `company_id`	Access token scoped to one company, plus refresh token
	`refresh_token`	`refresh_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`	`password`	`username`, `password`	Access token for the user, not bound to a company
`POST /core/latest/generic-token`	`refresh_token`	`refresh_token`	A new access token
`POST /core/latest/token/by-microsoft`	not applicable	`microsoft_access_token`, `tenant_id`	System token
`POST /core/latest/tenants`	not 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.

POST /core/latest/generic-token: Generate tokens to use KLARA specific endpoint
POST /core/latest/tenants: Returns all tenants of a user
POST /core/latest/token: Generate tokens to access other KLARA core endpoints
POST /core/latest/token/by-microsoft: Exchange Microsoft access token for system token

Keeping your API key safe

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

One key per use case. Name it so you can identify it later, for example integration-payroll-prod. When something goes wrong you can revoke one integration instead of all of them.
Never in client-side code. Not in a browser, not in a mobile app, not in anything a user can read. The key belongs on your server.
Never in a repository. Use environment variables or a secret manager. A key committed once stays in the Git history even after you delete the line.
Separate keys for development and live operation. There is only one environment, so the key name is what tells them apart. Delete the development key when you go live.
Rotate on staff changes. Anyone holding the assigned role can use the key. When someone leaves the team, rotate.
Revoke what you no longer use. Delete keys under Benutzer in KLARA as soon as an integration is retired.

What the platform does and does not do for you

Question	Answer
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 97 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 KLARA	Technical name	Endpoints reachable, of 98
Administrator	`company_administrator`	94
External user	`external_user`	94
Kundenbeziehungen	`customer_relationship_manager`	75
Buchhalter	`accountant`	61
Mitarbeiter und Lohn	`payroll_specialist`	59
Online Terminbuchung	`booking`	48
Zeit- und Materialrapporte	`reporter`	21
Objektmanager	`object_manager`	13

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

Sixteen 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.

Permission	Endpoints	Administrator	External user	Mitarbeiter und Lohn	Buchhalter	Kundenbeziehungen	Zeit- und Materialrapporte	Online Terminbuchung	Objektmanager
`FINANCE`	22	✓	✓	✓	✓	✓	–	✓	–
`ARTICLE`	21	✓	✓	–	–	✓	–	–	–
`ACCOUNTING`	13	✓	✓	–	✓	–	–	–	–
`ARTICLE_READ_ONLY`	7	✓	✓	✓	–	✓	✓	✓	–
`COMPENSATION`	4	✓	✓	✓	✓	✓	–	✓	–
`ACCOUNTING_GET_MASTER_VAT`	3	✓	✓	✓	✓	✓	–	–	–
`ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE`	2	✓	✓	✓	✓	–	–	–	–
`FINANCE_COMPANY_VAT`	2	✓	✓	✓	✓	–	–	–	–
`FINANCE_GET_CUSTOMER`	2	✓	✓	✓	–	✓	–	✓	–
`ACCOUNTING_GET_OPEN_POSITION`	1	✓	✓	–	✓	✓	–	–	–
`ACCOUNTING_INTERFACE`	1	✓	✓	✓	–	–	–	–	–
`COMPENSATION_COMPANY_INFO`	1	✓	✓	✓	✓	✓	✓	✓	✓
`COMPENSATION_TIME_TRACKING`	1	✓	✓	✓	–	–	✓	–	–
`FINANCE_BANK_ACCOUNT`	1	✓	✓	✓	✓	✓	–	–	–
`FINANCE_CREATE_CUSTOMER`	1	✓	✓	✓	–	✓	–	–	–
`STORE_CUSTOMER`	1	✓	✓	✓	✓	✓	–	✓	–

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

Only Kundenbeziehungen can write articles. Every other role reaches at most ARTICLE_READ_ONLY. An integration that maintains articles needs that role or an Administrator.
Online Terminbuchung can change and delete customers but not create them. The role holds FINANCE and FINANCE_GET_CUSTOMER, but not FINANCE_CREATE_CUSTOMER, and creating a customer checks that one instead of FINANCE.

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, Mitarbeiter und Lohn, Kundenbeziehungen.

What to watch out for

invoiceCode is the only required field in the request body, and it must be unique within the company. Everything else the schema marks as optional, which does not mean the business logic accepts an empty invoice.
id must be 0 or omitted. This endpoint creates, it never updates. Sending an existing id does not edit that invoice.
Step 1 is not idempotent. Each call reserves the next number and advances the counter. Call it immediately before creating the invoice, never speculatively, or you leave gaps in the sequence.
status drives everything downstream. Allowed values are DRAFT, INVOICED, SENT, PAID and CANCELLED. Create with INVOICED if you intend to send it, because sending rejects drafts.
postMethod is recorded, not executed. Setting it on the invoice does not deliver anything. Delivery is a separate call, see Sending documents.
Closing fiscal years are rejected unless you pass confirmDontMindClosingFiscalYear=true. Decide deliberately whether your integration should be allowed to do that.

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, Mitarbeiter und Lohn, Kundenbeziehungen.

What to watch out for

Always search before you create. There is no upsert and no uniqueness guarantee on email. Skipping step 1 gives you duplicate customers, and duplicates in the customer master are painful to merge afterwards.
customerType is the only required field on a customer, and it decides the shape of everything else. It is either a person or a company.
Step 4 is not idempotent. Each successful call performs a real delivery. After a timeout, do not simply retry, read the invoice back first, see Showing invoice status.

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

At least two lines, and they must balance. Total debit must equal total credit or the downstream service rejects the posting.
Required in the header: documentDate, bookingDate and bookingDetails. Required per line: accountCode, crdrType, description, amount, tags and bookingTypeCode.
amount is always positive. The sign is carried by crdrType, which is DR or CR.
Let the server do the VAT. With autoCalculateVat=true it recalculates the way the manual booking screen does, which is safer than computing it yourself.
Two guards will reject otherwise valid bookings: a date in a closing fiscal year, and a date outside the active KLARA Accounting subscription window. Both can be overridden with confirmDontMindClosingFiscalYear and ignore-unsubscripted-dates. Overriding is a business decision, not a technical one.
Tenant and company come from the token. The id and company fields in the body are ignored.

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

Step 1 is multipart/form-data, not JSON. Both category and file are required. The allowed categories are SALARY_STATEMENTS, YEARLY_REPORTS, PAYMENT_FILES, INSURANCE_CERTIFICATES, SALARY_TRANSMISSIONS, OWN_DOCUMENTS, LIABILITY_UPLOAD, EXPENSES and LIABILITIES.
LIABILITY_UPLOAD behaves differently. That category additionally triggers an asynchronous AI analysis downstream. Pick it deliberately, not as a default.
Maximum file size is 25 MB. Larger uploads fail with 413.
Step 2 replaces, it does not append. Send the complete list of document ids every time. An empty array clears all attachments. If you want to add a receipt, read the current list first and send it back with yours appended.
Step 2 is idempotent. Re-sending the same body produces the same result, so a retry after a timeout is safe here.
Only the company's own path id is accepted in step 1. The tenant comes from the token.

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

Paging is offset based and capped. On customers, limit defaults to 50 and is capped at 100. A request above the cap is rejected with 400, not quietly reduced. Iterate offset=0, 100, 200… until a page returns fewer rows than you asked for.
Both can be filtered, but differently. Customers take search-key, which searches name, email, phone and customer number, and status, which takes ACTIVE, ALL or ARCHIVED. Articles take product-type only. For free-text article search use GET /core/latest/articles/search with keyword.
Without status you only see active customers. A sync that omits it will never notice that a record was archived, and will keep it alive on your side forever.
Creating an article needs six fields: nameDE, unitDE, accountingTags, articleNumber, productType. Note that the required name and unit are the German ones, whatever language you otherwise work in.
There is no change feed. No webhook, no modified-since filter. A sync has to page through everything and compare, so run it on a schedule rather than continuously, and mind the rate limit.

Showing invoice status in your CRM

Read the current state of an invoice you created earlier.

GET /core/v1/invoices/{id}   → the full invoice including booking status

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

You need to have kept the invoice id Invoices cannot be listed, searched or filtered. There is no GET /core/v1/invoices collection. The only way back to an invoice is the numeric id returned when you created it, so store it in your own system at creation time. If you did not, the API cannot help you find it again. See Known limitations.

What to watch out for

The status values are DRAFT, INVOICED, SENT, PAID and CANCELLED.
The response also carries booking state: bookingStatus, bookingDueDate and bookingSealed.
Polling is the only option today. There are no webhooks, so poll gently and cache. See rate limiting.
This is also your recovery step. After a timeout on a create or send, read the invoice back before retrying.

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

The query string switches behaviour, it does not just filter. With code set you get those codes, otherwise with default-vat=true you get the company defaults, otherwise you get the whole catalogue ordered by rate.
Paging only works on the full catalogue. limit and offset are silently ignored when code or default-vat is set. Silently, so you will not get an error, just all the rows.
Combine code with current-period=true to get only rates valid today. VAT rows carry validity ranges, and using an expired rate is a real risk.
Labels are translatable. Send Accept-Language with de-CH, fr-CH, it-CH or en, see Response languages.

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

This data is global, not per company. The same chart of accounts comes back for every tenant, which is why there are no tenant or company parameters. Fetch it once and cache it.
legal-form both filters and translates. It restricts the result to accounts that carry a translation for that legal form, and resolves the name field from that translation. The allowed values are listed on the endpoint in the reference.
No permission is declared on this endpoint. Any authenticated token is accepted.
Read only, no side effects, so it is safe to call while you are exploring.

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.

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 "X-API-KEY: $KLARA_API_KEY" \
  -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 "X-API-KEY: $KLARA_API_KEY" \
  -H "Accept: application/json"

Value	Channel	Can be forced
`SEND_EMAIL`	Email to the recipient	yes
`EPOST`	ePost digital letterbox	yes
`EBILL`	eBill, straight into the recipient's e-banking	yes
`A_POST`	Printed and posted, A Post	yes
`B_POST`	Printed and posted, B Post	yes
`PRINT_AND_MANUAL_SEND`	Printed 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

23 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.

Schema	Fields
`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.

What	Value
Limit	At least 10,000 requests per minute
Counted against	The calling IP address, not the API key and not the company
Scope	The 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

Retry with exponential backoff. On 429, wait, then retry with an increasing delay. Do not retry in a tight loop.
Cache reference data. Accounts, VAT rates, booking types and article categories change rarely. Fetch them once per run, not per record.
Batch by run, not by record. Creating two hundred records means two hundred requests. Spread them out.

Pagination

9 endpoints accept pagination parameters:

Endpoint	Parameters
GET `/core/latest/article-categories`	`limit`, `offset`
GET `/core/latest/article-filters`	`limit`, `offset`
GET `/core/latest/articles`	`limit`, `offset`
GET `/core/latest/articles/article-and-variants`	`limit`, `offset`
GET `/core/latest/articles/search`	`limit`, `offset`
GET `/core/v1/accounting/business-case-templates`	`limit`, `offset`
GET `/core/v1/accounting/master-vats`	`limit`, `offset`
GET `/core/v1/customers`	`limit`, `offset`
GET `/core/v1/invoices`	`limit`, `offset`

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

Question	Answer
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

7 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.

Endpoint	Parameter
GET `/core/latest/article-categories`	`keyword`, `search-key`
GET `/core/latest/article-filters`	`keyword`, `search-key`
GET `/core/latest/articles/search`	`keyword`, `search-key`
GET `/core/v1/bank-reconciliation/open-positions`	`general-search`, `search-key`
GET `/core/v1/customers`	`search-key`
GET `/core/v1/employees/short-info`	`search-key`
GET `/core/v1/invoices`	`search-key`

Filtering by field

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

Endpoint	Parameters
GET `/core/latest/article-categories`	`active-status`
GET `/core/latest/article-filters`	`active-status`
GET `/core/latest/articles`	`product-type`
GET `/core/latest/articles/article-and-variants`	`include-quantity`, `sell-in-booking`, `sell-in-online-shop`, `use-pos`
GET `/core/latest/articles/article-numbers`	`article-numbers`, `export-vat`, `price-date`, `should-validate-vat`
GET `/core/latest/articles/search`	`export-vat`, `price-date`, `should-validate-vat`
POST `/core/latest/payroll-interface-file`	`file-format`, `payslip-ids`, `salary-run-id`
POST `/core/latest/subscriptions`	`marketing-code`
GET `/core/latest/vat-cases`	`applicability`
GET `/core/v1/accounting/accounts`	`legal-form`
GET `/core/v1/accounting/accounts/account-displaying`	`legal-form`
GET `/core/v1/accounting/accounts/by-code/{accountCode}`	`legal-form`
GET `/core/v1/accounting/business-cases`	`businessCaseTemplateId`, `dateForFilteringCompanyVat`, `dateForFilteringFiscalYear`
GET `/core/v1/accounting/business-cases/v2`	`businessCaseTemplateId`, `dateForFilteringCompanyVat`, `dateForFilteringFiscalYear`, `group-insurance-by-insurer`, `snippet-id`, `snippet-value`
GET `/core/v1/accounting/currencies/exchange-rate`	`exchange-date`, `from-currency-code`
GET `/core/v1/accounting/master-vats`	`code`, `current-period`, `default-vat`, `includeHiddenVatCase`
GET `/core/v1/accounting/vat-profile`	`date`
GET `/core/v1/accounting/vat-suggestions`	`accountCode`, `amount`, `amountKind`, `date`, `direction`, `vatCase`
GET `/core/v1/bank-reconciliation/open-positions`	`action`, `booking-type-codes`, `crdr-type`, `credit-card-not-reconciled`, `invoice-date`, `partner`, `payment-date`, `payment-date-from`, `payment-date-to`, `position-status`, `tags`
POST `/core/v1/bookings`	`autoCalculateVat`, `confirmDontMindClosingFiscalYear`, `ignore-unsubscripted-dates`
PUT `/core/v1/bookings/{id}/documents`	`ignore-unsubscripted-dates`
GET `/core/v1/company-bank-accounts`	`iban-number`, `type`
GET `/core/v1/customers`	`status`
GET `/core/v1/employees/short-info`	`filter-by-status`, `status`, `workplace-ids`
GET `/core/v1/invoices`	`booking-status`, `status`
PUT `/core/v1/invoices`	`confirmDontMindClosingFiscalYear`
POST `/core/v1/invoices`	`confirmDontMindClosingFiscalYear`
POST `/core/v1/invoices/{id}/send`	`channel`
GET `/core/v1/order-documents/filter/type-and-order-number`	`order-number`, `type`
GET `/core/v1/order-numbering-configurations`	`order-type`
POST `/core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-items`	`recalculate`
GET `/core/v1/payroll/employees/{employeeId}/addable-salary-items`	`month`
POST `/core/v1/vat-clearing-reports/{year}/{quarter}`	`recalculate`

Sorting

3 endpoints accept a sort order: /core/v1/accounting/business-case-templates, /core/v1/employees/short-info, /core/v1/invoices. Everywhere else the order is not guaranteed, which matters when you page through a large collection.

Invoices are the most important gap: there is no list endpoint at all, so they cannot be listed or filtered. You have to keep the ids you created. See Known limitations.

API reference

98 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

Accounting24

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

Name Description

Name	Description
`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

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

Name Description

Name	Description
`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

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.

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.

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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).

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`code` query string	Semicolon-separated list of `vatCode`s 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).

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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).

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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).

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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):

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.
Render the dropdowns per the table above; preselect the row where recommended = true.
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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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/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. 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:

Call GET /core/v1/accounting/vat-suggestions?direction=PURCHASE|SALE&amount=<gross>&date=<bookingDate> and take the recommended row.
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).
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
Reference to the business-case document (workflow id) that produced this booking, when applicable.
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. 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
Reference to the business-case document (workflow id) that produced this booking, when applicable.
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. 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.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch 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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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 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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung.

Parameters 7

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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:

Call GET /core/v1/invoices/next-invoice-number to obtain the next invoice number.
(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.
Look up the customer via GET /core/v1/customers (with search filters and pagination).
Look up company bank accounts via GET /core/v1/company-bank-accounts.
Search articles via GET /core/latest/articles/search or GET /core/latest/articles/article-numbers to populate order items.
(Optional) Look up open positions via GET /core/v1/bank-reconciliation/open-positions to reconcile prepayments / credit notes.
(Optional) Call POST /core/v1/orders/next-order-number to obtain the next order.orderNumber.
(Optional) Call GET /core/latest/company-configuration/including-vat to determine the company default for usingVAT.
Build the invoice payload with order items.
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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 2

Name	Description
`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.
(Optional) POST /core/v1/orders/next-order-number → provides order.orderNumber; 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.

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 POST /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.
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, required for booking) — tags field; must not be empty when status is INVOICED/SENT.
orderItems[].vatCase (String) — TAXABLE_SUPPLY, EXEMPT_SUPPLY, REVERSE_CHARGE.
orderItems[].articleType (String) — PRODUCTION, PREPAYMENT, SERVICE.
orderItems[].vat (object) — VAT details: vatCode, rate, description, masterId. For an export invoice (usingExportVat=true) set rate=0 and the export/zero vatCode.
orderItems[].id (long) — must be 0 for new items.

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 performs no VAT recalculation or consistency check. 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).

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

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.
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).

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.
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.

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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name	Description
`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:

Call POST /core/v1/invoices with status=DRAFT to create the invoice.
Call GET /core/v1/invoices/{id} to retrieve the current state.
Modify the desired fields (items, amounts, dates, etc.).
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 (String, required when booking) — 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).
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 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.
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).

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.
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).

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name	Description
`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.
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).

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 2

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 2

Name Description

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).

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name Description

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").

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name Description

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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`category-id` required path string

Responses 6

204 Deleted successfully no response body

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`filter-id` required path string

Responses 5

204 Delete successfully no response body

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

GET/core/latest/articles/searchkey / tokenFree-text search across sellable articles

Free-text search across sellable articles (and their variants) of the caller's company. Matches by name, article number, barcode, variant number and set-header name. Returns each row enriched with the price valid on `price-date` and the appropriate VAT rate. Requires permission `ARTICLE_READ_ONLY`.

operationId

searchSellableArticles — 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 7

Name	Description
`export-vat` query boolean	If `true`, return ABROAD (export) VAT rate; otherwise NORMAL. default: false
`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 key. Trimmed; empty/missing returns the first page unfiltered. maxLength: 256 example: paper
`limit` query integer	Page size (1–100). min: 1 max: 100 default: 50 example: 50
`offset` query integer	0-based pagination offset. min: 0 default: 0 example: 0
`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
`search-key` query string	Free-text search key. Trimmed; empty/missing returns the first page unfiltered. maxLength: 256 example: paper
`should-validate-vat` query boolean	If `true`, cross-validate each row's VAT code against the company's VAT setup on `price-date`. 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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Kundenbeziehungen, Online Terminbuchung

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
  Address list of this person
  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 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 a city for this address
  - 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
- 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
- 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
- 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
- addresses array of Address
  Address list of this company, atleast one should be add
  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 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 a city for this address
  - 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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, 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
  Address list of this person
  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 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 a city for this address
  - 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
- 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
- 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
- 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
- addresses array of Address
  Address list of this company, atleast one should be add
  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 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 a city for this address
  - 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
  Address list of this person
  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 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 a city for this address
  - 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
- 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
- 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
- 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
- addresses array of Address
  Address list of this company, atleast one should be add
  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 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 a city for this address
  - 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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name	Description
`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
  Address list of this person
  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 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 a city for this address
  - 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
- 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
- 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
- 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
- addresses array of Address
  Address list of this company, atleast one should be add
  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 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 a city for this address
  - 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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name	Description
`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
  Address list of this person
  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 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 a city for this address
  - 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
- 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
- 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
- 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
- addresses array of Address
  Address list of this company, atleast one should be add
  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 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 a city for this address
  - 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
  Address list of this person
  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 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 a city for this address
  - 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
- 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
- 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
- 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
- addresses array of Address
  Address list of this company, atleast one should be add
  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 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 a city for this address
  - 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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name	Description
`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 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 a city for this address
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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name	Description
`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 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 a city for this address
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 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 a city for this address
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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 2

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 2

Name	Description
`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 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 a city for this address
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 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 a city for this address
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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name	Description
`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
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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 1

Name	Description
`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
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
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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 2

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

Parameters 2

Name	Description
`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
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
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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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, Mitarbeiter und Lohn, Kundenbeziehungen, Online Terminbuchung

Parameters 4

Name	Description
`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
  Address list of this person
  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 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 a city for this address
  - 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
- 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
- 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
- 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
- addresses array of Address
  Address list of this company, atleast one should be add
  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 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 a city for this address
  - 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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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_TIME_TRACKING 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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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 recalculates that month unless recalculate=false. 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). 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 3

Name	Description
`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
`recalculate` query boolean	Whether to recalculate the payslip after adding the item. Defaults to true. default: true example: True

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 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").

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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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 the specified month's payslip is used (read-only); when it is omitted the employee's current editable payslip is used, which may be computed on first access. 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

Name	Description
`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 editable payslip is used. 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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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. Can be one of the following:
- Limited liability company(GmbH)
- Public limited company (AG)
- Individually owned company (EU)
- Association (V)
- Simple partnership (EG)
- General partnership (KG)
- Limited partnership (KDG)
- Cooperative company (G)
- Foundation (S)
- OR
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
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
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 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 a city for this address
- 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

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. Can be one of the following:
- Limited liability company(GmbH)
- Public limited company (AG)
- Individually owned company (EU)
- Association (V)
- Simple partnership (EG)
- General partnership (KG)
- Limited partnership (KDG)
- Cooperative company (G)
- Foundation (S)
- OR
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
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
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 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 a city for this address
- 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

application/json ErrorResponse

error string
Summary of the error response
error_description string
Description of the error response

application/json ErrorResponse

error string
Summary of the error response
error_description string
Description of the error response

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. Can be one of the following:
- Limited liability company(GmbH)
- Public limited company (AG)
- Individually owned company (EU)
- Association (V)
- Simple partnership (EG)
- General partnership (KG)
- Limited partnership (KDG)
- Cooperative company (G)
- Foundation (S)
- OR
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
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
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 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 a city for this address
- 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. Can be one of the following:
- Limited liability company(GmbH)
- Public limited company (AG)
- Individually owned company (EU)
- Association (V)
- Simple partnership (EG)
- General partnership (KG)
- Limited partnership (KDG)
- Cooperative company (G)
- Foundation (S)
- OR
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
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
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 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 a city for this address
- 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)

application/json ErrorResponse

error string
Summary of the error response
error_description string
Description of the error response

application/json ErrorResponse

error string
Summary of the error response
error_description string
Description of the error response

application/json ErrorResponse

error string
Summary of the error response
error_description string
Description of the error response

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
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter, Kundenbeziehungen, Online Terminbuchung

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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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_VAT
Available through: Administrator, External user, Mitarbeiter und Lohn, Buchhalter

Parameters 1

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

Name	Description
`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.
- 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

application/json ErrorResponse

error string
Summary of the error response
error_description string
Description of the error response

application/json ErrorResponse

error string
Summary of the error response
error_description string
Description of the error response

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

application/json ErrorResponse

error string
Summary of the error response
error_description string
Description of the error response

application/json ErrorResponse

error string
Summary of the error response
error_description string
Description of the error response

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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.

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

application/json ErrorMessage

uuid string
createdTime string
code string
message string
detail string deprecated

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

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

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.

No webhooks. There is no way to be notified of invoice or payment events, so you need to poll, and poll gently. See rate limiting.
No general order resource. For webshop integrations, create a customer and an invoice instead.
Free-text search exists on a handful of endpoints only. Everywhere else you need to know the value you are looking for, because filtering by field is not the same as searching. Searching and filtering lists both, counted from the contract.
Payroll master data is not writable. Variable salary items are writable, see Submitting variable payroll data, but contracts and base salaries are not.
No appointment booking API, despite the role name in KLARA.
No PATCH. Partial updates require a complete PUT.

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?

Every endpoint that requires authentication accepts either an API key or a bearer token, so the method is not the problem. Check three things instead: 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. Note that the token endpoints themselves take no authentication at all, listed under Authentication.

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.