Specification

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.

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

`configuration`
Optionaltype: object

`enableOpenItems`
Optionaltype: 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`
Optionaltype: enum

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

Allowed values:
- csv CSV single entries export (file)
- json JSON collective entries export (file)

`journalExportExportsFiles`
Optionaltype: 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`
Optionaltype: 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`
Optionaltype: string

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

Example: https://my.host.com/kontera-webhook-processing
SSL/TLS is mandatory
Min: 10 Characters
Max: 512 Characters

`webhookSecret`
Optionaltype: 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.

"organization": {
    "companyName": "bexio ag",
    "companyUid": "CHE-123.456.789",
    "companyTaxNumber": "CHE-123.456.789 MWST",
    "leadCurrency": "CHF"
}

`organization`
Requiredtype: object

`companyName`
Requiredtype: string

Name of your company.

Min: 1 character
Max: 255 characters

`companyUid`
Requiredtype: stringAI

Company UID.

Min: 1 character
Max: 255 characters

`companyTaxNumber`
Requiredtype: stringAI

VAT Number.

Min: 1 character
Max: 255 characters

`leadCurrency`
Requiredtype: string

The lead currency of your accounting.

ISO 4217 currency code
Example: CHF

Currencies

Available currencies of your accounting system.

"currencies": [
    {
      "externalId": "1",
      "code": "CHF"
    },
  {
      "externalId": "2",
      "code": "EUR"
  }
]

`currencies`
Requiredtype: array

`externalId`
Requiredtype: 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`
Requiredtype: string

3-character ISO currency code.

ISO 4217 currency code

Chart of accounts

Chart of accounts of your accounting system:

"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`
Requiredtype: array

`externalId`
Requiredtype: 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`
Requiredtype: string

Number of name of your account, for example: 6510

Min: 1 character
Max: 12 characters

`description`
Requiredtype: string

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

Type: string
Min: 1 character
Max: 255 characters

`defaultTaxId`
Optionaltype: 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`
Optionaltype: string

Currency of this account.

For regular currencies, use ISO 4217 currency code

`usedForPayments`
Optionaltype: 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`
Optionaltype: string

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

IBAN

`qrIban`
Optionaltype: string

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

🇨🇭-only
QR-IBAN

`taxRequired`
Optionaltype: 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`
Optionaltype: 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.

"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`
Requiredtype: array

`externalId`
Requiredtype: 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`
Requiredtype: string

Short code to identify your tax.

Min: 1 character
Max: 12 characters

`description`
Requiredtype: string

Description for your tax.

Min: 1 character
Max: 255 characters

`value`
Requiredtype: string

%-value of your tax.

Min: 0
Max: 100

`type`
Requiredtype: string

Type of your tax.

Allowed values:
- pre-tax
- reverse-charge-pre-tax
- sales-tax

`country`
Optionaltype: string

Country this tax applies to.

Min: 2 characters
Max: 2 characters

`startsAt`
Requiredtype: string

Date from which tax is valid.

Date in ISO-format YYYY-MM-DD

`endsAt`
Optionaltype: string

Date until which tax is valid. Can be omitted.

Date in ISO-format YYYY-MM-DD

`swissVatFormDigit`
Optionaltype: string | null

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.

Exactly 3 characters or null
🇨🇭-only

`swissVatFormDigitForReverseChargeLiability`
Optionaltype: string | null

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.

Exactly 3 characters or null
🇨🇭-only

`postToAccountExternalId`
Optionaltype: 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`
Optionaltype: 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.

"taxPeriods": [
    {
       "externalId": "1",
      "isSubjectToTax": true,
      "balanceTaxation": false,
      "accountingMethod": "accrual-basis",
      "startsAt": "2023-01-01",
      "endsAt": "2023-12-31"
    }
]

`taxPeriods`
Requiredtype: array

`externalId`
Requiredtype: 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`
Requiredtype: boolean

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

Allowed values:
- true
- false

`balanceTaxation`
Requiredtype: boolean

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

Allowed values:
- true
- false

`accountingMethod`
Requiredtype: enum

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

Allowed values:
- accrual_basis
- cash_basis

`startsAt`
Requiredtype: string

Beginning of tax period.

Date in ISO-format YYYY-MM-DD

`endsAt`
Requiredtype: 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.

"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`
Requiredtype: array

`contactId`
Optionaltype: 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`
Requiredtype: 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`
Requiredtype: enum

Describes the type of legal entity the contacts represents.

Allowed values:
- company
- person

`supplierType`
Optionaltype: enum

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

Allowed values:
- accounts-payable
- accounts-receivable

`companyName`
Optionaltype: string

Required if legalType = company

Min: 1 character
Max: 255 characters

`companyUid`
Optionaltype: string

Company UID.

Min: 1 character
Max: 255 characters

`companyTaxNumber`
Optionaltype: string

VAT Number of your company.

Min: 1 character
Max: 255 characters

`firstName`
Optionaltype: string

Required if legalType = person

Min: 1 character
Max: 255 characters

`lastName`
Optionaltype: string

Required if legalType = person

Min: 1 character
Max: 255 characters

`address`
Optionaltype: object

`street`
Optionaltype: string

Name of street.

Min: 1 character
Max: 255 characters

`street`
Optionaltype: string

Name of street.

Min: 1 character
Max: 255 characters

`houseNumber`
Optionaltype: string

House number.

Min: 1 character
Max: 255 characters

`postalCode`
Optionaltype: string

Postal code / ZIP code.

Min: 1 character
Max: 255 characters

`city`
Optionaltype: string

Name of city.

Min: 1 character
Max: 255 characters

`country`
Optionaltype: string

Country.

2-letter ISO3166 code

Projects

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

"projects": [
    {
        "externalId": "1",
        "code": "PRO-1",
        "name": "Kundenprojekt 1"
    }
]

`projects`
Requiredtype: array

`externalId`
Requiredtype: 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`
Requiredtype: string

Name or short description of project.

Min: 1 character
Max: 255 characters

`code`
Requiredtype: 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.

"costCenters": [
    {
        "externalId": "1",
        "code": "CC-RD",
        "name": "Kostenstelle R&D"
    }
]

`costCenters`
Requiredtype: array

`externalId`
Requiredtype: 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`
Requiredtype: string

Name or short description of cost center.

Min: 1 character
Max: 255 characters

`code`
Requiredtype: string

Code of cost center.

Min: 1 character
Max: 12 characters

Specification

Configuration

configurationOptionaltype: object

configurationOptionaltype: object

enableOpenItemsOptionaltype: boolean

journalExportFormatOptionaltype: enum

journalExportExportsFilesOptionaltype: boolean

journalExportUsesWebhookOptionaltype: string

webhookUrlOptionaltype: string

webhookSecretOptionaltype: string

Organization

organizationRequiredtype: object

organizationRequiredtype: object

companyNameRequiredtype: string

companyUidRequiredtype: stringAI

companyTaxNumberRequiredtype: stringAI

leadCurrencyRequiredtype: string

Currencies

currenciesRequiredtype: array

currenciesRequiredtype: array

externalIdRequiredtype: string

codeRequiredtype: string

Chart of accounts

accountsRequiredtype: array

accountsRequiredtype: array

externalIdRequiredtype: string

numberRequiredtype: string

descriptionRequiredtype: string

defaultTaxIdOptionaltype: string

currencyOptionaltype: string

usedForPaymentsOptionaltype: boolean

ibanOptionaltype: string

qrIbanOptionaltype: string

taxRequiredOptionaltype: boolean

typeOptionaltype: enum

Taxes

taxesRequiredtype: array

taxesRequiredtype: array

externalIdRequiredtype: string

codeRequiredtype: string

descriptionRequiredtype: string

valueRequiredtype: string

typeRequiredtype: string

countryOptionaltype: string

startsAtRequiredtype: string

endsAtOptionaltype: string

swissVatFormDigitOptionaltype: string | null

swissVatFormDigitForReverseChargeLiabilityOptionaltype: string | null

postToAccountExternalIdOptionaltype: string

reverseChargeLiabilityAccountExternalIdOptionaltype: string

Tax periods

taxPeriodsRequiredtype: array

taxPeriodsRequiredtype: array

externalIdRequiredtype: string

isSubjectToTaxRequiredtype: boolean

balanceTaxationRequiredtype: boolean

accountingMethodRequiredtype: enum

startsAtRequiredtype: string

endsAtRequiredtype: string

Contacts

contactsRequiredtype: array

contactsRequiredtype: array

contactIdOptionaltype: string

externalIdRequiredtype: string

legalTypeRequiredtype: enum

supplierTypeOptionaltype: enum

companyNameOptionaltype: string

companyUidOptionaltype: string

companyTaxNumberOptionaltype: string

firstNameOptionaltype: string

lastNameOptionaltype: string

addressOptionaltype: object

addressOptionaltype: object

streetOptionaltype: string

streetOptionaltype: string

houseNumberOptionaltype: string

postalCodeOptionaltype: string

cityOptionaltype: string

countryOptionaltype: string

Projects

`configuration`
Optionaltype: object

`configuration`
Optionaltype: object

`enableOpenItems`
Optionaltype: boolean

`journalExportFormat`
Optionaltype: enum

`journalExportExportsFiles`
Optionaltype: boolean

`journalExportUsesWebhook`
Optionaltype: string

`webhookUrl`
Optionaltype: string

`webhookSecret`
Optionaltype: string

`organization`
Requiredtype: object

`organization`
Requiredtype: object

`companyName`
Requiredtype: string

`companyUid`
Requiredtype: stringAI

`companyTaxNumber`
Requiredtype: stringAI

`leadCurrency`
Requiredtype: string

`currencies`
Requiredtype: array

`currencies`
Requiredtype: array

`externalId`
Requiredtype: string

`code`
Requiredtype: string

`accounts`
Requiredtype: array

`accounts`
Requiredtype: array

`externalId`
Requiredtype: string

`number`
Requiredtype: string

`description`
Requiredtype: string

`defaultTaxId`
Optionaltype: string

`currency`
Optionaltype: string

`usedForPayments`
Optionaltype: boolean

`iban`
Optionaltype: string

`qrIban`
Optionaltype: string

`taxRequired`
Optionaltype: boolean

`type`
Optionaltype: enum

`taxes`
Requiredtype: array

`taxes`
Requiredtype: array

`externalId`
Requiredtype: string

`code`
Requiredtype: string

`description`
Requiredtype: string

`value`
Requiredtype: string

`type`
Requiredtype: string

`country`
Optionaltype: string

`startsAt`
Requiredtype: string

`endsAt`
Optionaltype: string

`swissVatFormDigit`
Optionaltype: string | null

`swissVatFormDigitForReverseChargeLiability`
Optionaltype: string | null

`postToAccountExternalId`
Optionaltype: string

`reverseChargeLiabilityAccountExternalId`
Optionaltype: string

`taxPeriods`
Requiredtype: array

`taxPeriods`
Requiredtype: array

`externalId`
Requiredtype: string

`isSubjectToTax`
Requiredtype: boolean

`balanceTaxation`
Requiredtype: boolean

`accountingMethod`
Requiredtype: enum

`startsAt`
Requiredtype: string

`endsAt`
Requiredtype: string

`contacts`
Requiredtype: array

`contacts`
Requiredtype: array

`contactId`
Optionaltype: string

`externalId`
Requiredtype: string

`legalType`
Requiredtype: enum

`supplierType`
Optionaltype: enum

`companyName`
Optionaltype: string

`companyUid`
Optionaltype: string

`companyTaxNumber`
Optionaltype: string

`firstName`
Optionaltype: string

`lastName`
Optionaltype: string

`address`
Optionaltype: object

`address`
Optionaltype: object

`street`
Optionaltype: string

`street`
Optionaltype: string

`houseNumber`
Optionaltype: string

`postalCode`
Optionaltype: string

`city`
Optionaltype: string

`country`
Optionaltype: string

`projects`
Requiredtype: array

`projects`
Requiredtype: array

`externalId`
Requiredtype: string

`name`
Requiredtype: string

`code`
Requiredtype: string

`costCenters`
Requiredtype: array

`costCenters`
Requiredtype: array

`externalId`
Requiredtype: string

`name`
Requiredtype: string