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.

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.

• ISO 4217 currency code
• Example: CHF

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.

• ISO 4217 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",
        "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.

• For regular currencies, use ISO 4217 currency code

iban

Optional type: string

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

• IBAN

qrIban

Optional type: string

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

• 🇨🇭-only
• 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