Skip to content
/kontera/dev

API reference

All imports using the Universal Accounting consist of the following fields / data. Please reference the individual formats to get an example of a specific import structure.

Configuration

Basic configuration options for your accounting system.

kontera.json
"configuration": {
    "enableOpenItems": true,
    "journalExportFormat": "json",
    "journalExportExportsFiles": true,
    "journalExportUsesWebhook": true,
    "webhookUrl":"https://my.host.com/kontera-webhook-processing",
    "webhookSecret" "your-webhook-hmac-secret"
},
configuration
Optional type: object
enableOpenItems
Optional type: boolean

This settings allows you to enable or disable the creation of open items and open items with payment advises. Works only in combination with the journalExportFormat = json.

  • If set to true, Kontera will allow to create and export open items and/or open items with payment advises.
  • If set to false, Kontera will not allow to create open items and/or open items with payment advises.
journalExportFormat
Optional type: enum

Format of the journal export as described in the section “export”.

journalExportExportsFiles
Optional type: boolean

Works only in combination with the journalExportFormat = json.

  • If set to true, Kontera will export/embed files as base64 encoded strings. See JSON collective entries export (file)
  • if set to false, Kontera will not export/embed files in the export.
journalExportUsesWebhook
Optional type: string

Works only in combination with the journalExportFormat = json.

  • If set to true, Kontera send a POST request to this URL with the exported journal entries as payload.
  • if set to false, Kontera will not send any requests for generated exports.
webhookUrl
Optional type: string

Kontera will send a POST request to this URL with the exported journal entries as payload.

webhookSecret
Optional type: string

Alongside every Webhook request, Kontera will send a X-Hub-Signature-256 header, containing a HMAC-SHA256 hash. After receiving a webhook on your end, you should calculate the corresponding HMAC hash using your secret and compare it to the sent hash in the received header. This way, you can make sure that the request has not been tampered with and was sent by Kontera. For an example on how to validate such requests, simply check out Github’s excellent documentation about the mechanism.

  • Min: 10 Characters
  • Max: 256 Characters

Organization

Basic info about your organization and company. Some of the fields help our AI when extracting data.

kontera.json
"organization": {
    "companyName": "Kontera GmbH",
    "companyUid": "CHE-123.456.789",
    "companyTaxNumber": "CHE-123.456.789 MWST",
    "leadCurrency": "CHF"
}
organization
Required type: object
companyName
Required type: string

Name of your company.

  • Min: 1 character
  • Max: 255 characters
companyUid
Required type: string AI

Company UID.

  • Min: 1 character
  • Max: 255 characters
companyTaxNumber
Required type: string AI

VAT Number.

  • Min: 1 character
  • Max: 255 characters
leadCurrency
Required type: string

The lead currency of your accounting.

Currencies

Available currencies of your accounting system.

kontera.json
"currencies": [
    {
      "externalId": "1",
      "code": "CHF"
    },
  {
      "externalId": "2",
      "code": "EUR"
  }
]
currencies
Required type: array
externalId
Required type: string

Internal ID of your currency in your accounting system. kontera uses this ID to uniquely identify your currency, and will reference it in the export.

  • Min: 1 character
  • Max: 36 characters
code
Required type: string

3-character ISO currency code.

Chart of accounts

Chart of accounts of your accounting system:

kontera.json
"accounts": [
    {
        "externalId": "1",
        "number": "1020",
        "description": "Bank",
        "iban": "CH9300762011623852957",
        "qrIban": "CH3300762011623852957",
        "usedForPayments": true,
        "currency": "CHF"
    },
    {
        "externalId": "2",
        "number": "1090",
        "description": "Credit card"
    },


  ...


    {
        "externalId": "658",
        "number": "6510",
        "description": "Communication costs",
        "defaultTaxExternalId": "1"
  }


  ...
]
accounts
Required type: array
externalId
Required type: string

Internal ID of your account in your accounting system. kontera uses this ID to uniquely identify your account, and will reference it in the export.

  • Min: 1 character
  • Max: 36 characters
number
Required type: string

Number of name of your account, for example: 6510

  • Min: 1 character
  • Max: 12 characters
description
Required type: string

Description of your account, for example “communication costs”.

  • Type: string
  • Min: 1 character
  • Max: 255 characters
defaultTaxId
Optional type: string

Internal ID of the default tax which is used with this account. kontera uses this information internally to improve its suggestions.

  • Min: 1 character
  • Max: 36 characters
currency
Optional type: string

Currency of this account.

usedForPayments
Optional type: boolean

  • If set to true, this account can be used to generate payment advises with. Ideally, also set its iban.

  • If set to false or null, this account cannot be used to make payments from.

  • Default is null.

iban
Optional type: string

If this account corresponds to a banking account, please include the corresponding IBAN.

qrIban
Optional type: string

If this account corresponds to a banking account, please include the corresponding QR-IBAN.

taxRequired
Optional type: boolean

  • If set to true, a tax is always required in combination with this account.

  • If set to false, you are forbidden from using a tax in combination with this account.

  • Default is null.

type
Optional type: enum

What kind of account it is.

  • Allowed values:
    • asset, Asset Account (active)
    • revenue, Revenue Account
    • liability, Liability Account (passive)
    • expense, Expense Account
    • equity Equity Account

Taxes

Describe the used tax codes in your accounting system.

kontera.json
"taxes": [
    {
      "externalId": "1",
      "code": "VB77",
      "description": "MWST 7.7%",
      "value": "7.7",
      "type": "pre-tax",
      "startsAt": "2020-01-01",
      "endsAt": "2023-12-31",
      "postToAccountExternalId": "10"
    }
]
taxes
Required type: array
externalId
Required type: string

Internal ID of your tax in your accounting system. kontera uses this ID to uniquely identify your tax, and will reference it in the export.

  • Min: 1 character
  • Max: 36 characters
code
Required type: string

Short code to identify your tax.

  • Min: 1 character
  • Max: 12 characters
description
Required type: string

Description for your tax.

  • Min: 1 character
  • Max: 255 characters
value
Required type: string

%-value of your tax.

  • Min: 0
  • Max: 100
type
Required type: string

Type of your tax.

  • Allowed values:
    • pre-tax
    • reverse-charge-pre-tax
    • sales-tax
country
Optional type: string

Country this tax applies to.

  • Min: 2 characters
  • Max: 2 characters
startsAt
Required type: string

Date from which tax is valid.

  • Date in ISO-format YYYY-MM-DD
endsAt
Optional type: string

Date until which tax is valid. Can be omitted.

  • Date in ISO-format YYYY-MM-DD
swissVatFormDigit
Optional type: string

Which code the tax rate corresponds on the Swiss VAT form. Kontera does not generate any VAT journal entries currently, so this information isn’t mandatory.

  • Min: 3 characters
  • Max: 3 characters
  • 🇨🇭-only
swissVatFormDigitForReverseChargeLiability
Optional type: string

Which code the tax rate corresponds on the Swiss VAT form. Kontera does not generate any VAT journal entries currently, so this information isn’t mandatory.

  • Min: 3 characters
  • Max: 3 characters
  • 🇨🇭-only
postToAccountExternalId
Optional type: string

Which account the tax should be posted in. Kontera does not generate any VAT journal entries currently, so this information isn’t mandatory.

  • Min: 1 character
  • Max: 36 characters
reverseChargeLiabilityAccountExternalId
Optional type: string

If your tax has type = reverse-charge-pre-tax, this determines the account on which the reverse-charge taxes gets posted upon.

  • Min: 1 character
  • Max: 36 characters

Tax periods

The tax periods of your accounting system. This concept might or might not exist in your target system, but its important for kontera in order to generate the correct journal entries.

kontera.json
"taxPeriods": [
    {
       "externalId": "1",
      "isSubjectToTax": true,
      "balanceTaxation": false,
      "accountingMethod": "accrual-basis",
      "startsAt": "2023-01-01",
      "endsAt": "2023-12-31"
    }
]
taxPeriods
Required type: array
externalId
Required type: string

Internal ID of your tax period in your accounting system. kontera uses this ID to uniquely identify your tax period, and will reference it in the export.

  • Min: 1 character
  • Max: 36 characters
isSubjectToTax
Required type: boolean

Whether your company is subject to VAT during the tax period.

  • Allowed values:
    • true
    • false
balanceTaxation
Required type: boolean

Whether your company is subject to balance taxation during the tax period.

  • Allowed values:
    • true
    • false
accountingMethod
Required type: enum

Described using what method your taxes are applied to journal entries.

  • Allowed values:
    • accrual_basis
    • cash_basis
startsAt
Required type: string

Beginning of tax period.

  • Date in ISO-format YYYY-MM-DD
endsAt
Required type: string

End of tax period.

  • Date in ISO-format YYYY-MM-DD

Contacts

Contacts can be optionally assigned to any ledger entry made in Kontera.

kontera.json
"contacts": [
    {
        "contactId": "885b42f7-3ce9-4cea-b617-3aed85cf1143",
        "externalId": "1",
        "legalType": "company",
        "supplierType": "accounts-payable",
        "companyName": "Beispiel GmbH",
        "companyUid": "CHE-123.456.789",
        "companyTaxNumber": "CHE-123.456.789 MWST",
        "firstName": null,
        "lastName": null,
        "address": {
            "street": "Example Street",
            "houseNumber": "42",
            "postalCode": "8051",
            "city": "Zürich",
            "country": "CH"
        }
    }
]
contacts
Required type: array
contactId
Optional type: string

Unique ID within kontera. You must provide this value together with an externalId generated by your system if you have added contacts into your system and are re-importing those contacts, to avoid duplication.

  • UUID
  • Required if contact was freshly created and does not know its externalId within Kontera
externalId
Required type: string

Internal ID of your project in your accounting system. kontera uses this ID to uniquely identify your project, and will reference it in the export.

  • Min: 1 character
  • Max: 36 characters
legalType
Required type: enum

Describes the type of legal entity the contacts represents.

  • Allowed values:
    • company
    • person
supplierType
Optional type: enum

Describes what kind of contact it is. Used by certain accounting systems with split contact pools.

  • Allowed values:
    • accounts-payable
    • accounts-receivable
companyName
Optional type: string

Required if legalType = company

  • Min: 1 character
  • Max: 255 characters
companyUid
Optional type: string

Company UID.

  • Min: 1 character
  • Max: 255 characters
companyTaxNumber
Optional type: string

VAT Number of your company.

  • Min: 1 character
  • Max: 255 characters
firstName
Optional type: string

Required if legalType = person

  • Min: 1 character
  • Max: 255 characters
lastName
Optional type: string

Required if legalType = person

  • Min: 1 character
  • Max: 255 characters
address
Optional type: object
street
Optional type: string

Name of street.

  • Min: 1 character
  • Max: 255 characters
street
Optional type: string

Name of street.

  • Min: 1 character
  • Max: 255 characters
houseNumber
Optional type: string

House number.

  • Min: 1 character
  • Max: 255 characters
postalCode
Optional type: string

Postal code / ZIP code.

  • Min: 1 character
  • Max: 255 characters
city
Optional type: string

Name of city.

  • Min: 1 character
  • Max: 255 characters
country
Optional type: string

Country.

  • 2-letter ISO3166 code

Projects

Projects are a possible dimension of your accounting system, and Kontera supports it natively.

kontera.json
"projects": [
    {
        "externalId": "1",
        "code": "PRO-1",
        "name": "Kundenprojekt 1"
    }
]
projects
Required type: array
externalId
Required type: string

Internal ID of your project in your accounting system. kontera uses this ID to uniquely identify your project, and will reference it in the export.

  • Min: 1 character
  • Max: 36 characters
name
Required type: string

Name or short description of project.

  • Min: 1 character
  • Max: 255 characters
code
Required type: string

Code of project.

  • Min: 1 character
  • Max: 12 characters

Cost centers

Cost centers are a possible dimension of your accounting system, and Kontera supports it natively.

kontera.json
"costCenters": [
    {
        "externalId": "1",
        "code": "CC-RD",
        "name": "Kostenstelle R&D"
    }
]
costCenters
Required type: array
externalId
Required type: string

Internal ID of your cost center in your accounting system. kontera uses this ID to uniquely identify your cost center, and will reference it in the export.

  • Min: 1 character
  • Max: 36 characters
name
Required type: string

Name or short description of cost center.

  • Min: 1 character
  • Max: 255 characters
code
Required type: string

Code of cost center.

  • Min: 1 character
  • Max: 12 characters