REST Import API Reference

Getting Started

Global Functions

Lucanet Lume

Data Hub

Administration

Extended Planning & Analysis (xP&A)

Consolidation & Financial Planning

ESG Reporting

Disclosure Management

XBRL Tagger

Lease Accounting

Banking & Cash Management

Data Collection

Tax Compliance & Reporting

Tax Administration

Income Taxes

User Interface of Income Taxes

Modules and Additional Functions in Income Taxes

Income Tax Forms

Master Data

Company

Status

Basic Data

Import

Import Suite

Interface to Lucanet Consolidation and Financial Planning (CFP)

REST Push Import Interface

REST Import API Reference

Deferred Taxes

Current Taxes

Tax Liabilities

KapEStA

Electronic Transmission

Data Transfer

Data Export

Validation

Comments

Snapshots

True-Up

(Sub-) Group

Reporting

Pillar 2

Country-by-Country Reporting

First Steps in Pillar 2 and CbCR

Tax Balance

Tax Services

Glossary

The REST import API lets an external system push balance sheet and P&L values into the Tax Data Hub, where the Income Taxes module imports them through the Import Suite. This page is the technical reference for developers who integrate an external system with the API. It describes the endpoint, the authentication, the request fields, the validation rules, the import behavior, and the response codes.

This reference covers the technical contract of the API only. To set up the interface in the application and run the import, see REST Push Import Interface.

The API does not validate the following aspects automatically. You must handle them in your external system, otherwise you risk database errors or data loss.

Validate these on the client side before you send a request:

Field lengths:

Keep every string field within 255 characters.

String trimming:

Remove leading and trailing spaces from every string field.

value precision:

Use a maximum of 24 digits in total, with 4 decimal places.

Batching:

Send all entries for the same combination of

year

month

unitId

, and

ledger

in a single request.

partner:

Use consistent values — always provide a value, or always leave it empty, for the same business case.

Also keep the following behaviors in mind:

Delete-insert logic:

When you send data for a (

year

month

unitId

ledger

) combination, the API deletes

all

existing data for that combination and replaces it with the new data.

Batching limitation:

You must send all entries for the same (

year

month

unitId

ledger

) combination together in one request. If you split them across requests, you lose data.

Empty partner:

If you do not provide

partner

, the API automatically stores an empty string.

No automatic length check:

Strings that exceed 255 characters cause database errors.

No enforced request limit:

Very large requests (more than 50,000 entries) can run into timeouts.

Send the data as a JSON array to a single endpoint:

Property	Value
Method	`POST`
Path	`/api/dataInput`
Content-Type	`application/json`

The base URL includes a /datasources segment, for example https://<tenant>.gtc-tax-data-hub.api.<region>.lucanet.cloud/datasources. To find the exact base URL, copy the link from the corresponding menu item in your environment.

You authenticate each request with the API token that you create in Tax Administration. Use the following header:

Header
`x-api-key: <api-key>`

Keep the API token confidential and do not share it with third parties. For details on how to create a token, see API Tokens.

The request body is a JSON array. Each array element is one data entry. The following example shows a single entry with the required fields and a few optional fields:

json

You must provide all of the following fields for every entry. If any of them is empty, the API rejects the entry.

Field	Type	Description
year	String	The four-digit year the data applies to. Max. 255 characters. Example: 2025
month	String	The month from 1 to 12. Max. 255 characters. Example: 12
unitId	String	The entity identifier. Max. 255 characters. Example: DE001
ledger	String	The ledger. Possible values: IFRS, HGB, TAX.
positionId	String	The account identifier. Max. 255 characters. Example: 120000520
value	Number	The amount, of type `DECIMAL(24,4)`: a maximum of 24 digits in total, of which 4 are decimal places. Example: 1000.50

You can add the following fields as needed:

Field	Type	Description
partner	String	An optional partner identifier. It is part of the unique constraint. Max. 255 characters. Example: AT002
currency	String	An optional currency code. Max. 255 characters. Example: EUR
addParameter1 to addParameter10	String	Generic fields for additional information. Your external system defines what these fields mean and how you use them. The downstream module — for example Income Taxes — then interprets and uses these values according to its configuration. Max. 255 characters each. Example: CustomValue1

The API does not trim string fields or validate their length automatically. Make sure that you keep every string field within 255 characters.

The API applies the following validations:

All mandatory fields (year, month, unitId, ledger, positionId, value) must be present and not empty. If a field is missing, the API returns:

The fields year and month must contain numeric values. If they do not, the API returns:

year:

must be a four-digit number, for example

2025

month:

must be a number from 1 to 12.

value:

must be a decimal number with a maximum of 24 digits, of which 4 are decimal places.

The combination of year, month, unitId, ledger, positionId, and partner must be unique. Because the API deletes all affected entries before it inserts the new ones, a unique-constraint error only occurs when the same combination appears more than once within a single request.

The API currently does not enforce strict limits on request size or the number of entries. Even so, your external system should follow these recommendations.

All string fields have a maximum length of 255 characters in the database. The API does not validate field lengths automatically, so strings that are too long cause database errors. Validate the length of every string field on the client side before you send the request. This applies to year, month, unitId, ledger, positionId, partner, currency, and addParameter1 to addParameter10.

The value field is of type DECIMAL(24,4): a maximum of 24 digits in total, of which 4 are decimal places.

Example	Valid?
`999999999999999999.9999` (24 digits)	✅ Valid
`1000.50`	✅ Valid
`-2500.7500`	✅ Valid
`9999999999999999999.9999` (25 digits)	❌ Invalid

A value of 0 is allowed, but null is not, because value is a mandatory field. Negative values are allowed and represent debit/credit postings. Validate on the client side that value is not null and does not exceed 24 digits (4 of them decimal places).

The partner field is optional, but it is part of the unique constraint (year, month, unitId, ledger, positionId, partner). For consistent behavior, choose one of these approaches and apply it consistently:

Option 1:

Always provide a value for

partner

, for example a default such as

NONE

when no partner applies.

Option 2:

Always leave

partner

empty, but do so consistently for the same business case.

If you send several entries with the same (year, month, unitId, ledger, positionId) combination but different partner values, the API stores them as separate entries. Aggregate your data on the client side before you send it to avoid unintended duplicates.

The API does not trim strings automatically. As a result, the API treats "DE001", " DE001 ", and "DE001 " as three different values:

json

Trim all string values on the client side, that is, remove leading and trailing spaces, before you send the request.

The API accepts all Unicode characters, and prepared statements prevent SQL injection. Still, avoid control characters such as \n, \t, and \r, and use consistent UTF-8 encoding.

The API uses a delete-insert logic to prevent duplicate values. For every request, the API first determines the unique combinations of year, month, unitId, and ledger in the incoming data. It then deletes all existing entries for these combinations from the database — regardless of positionId or partner — and inserts the new entries afterwards.

The system runs the DELETE and the INSERT operations in separate transactions. Make sure that each request contains the complete set of values for a given year, month, unitId, and ledger combination, because the delete step removes all previously stored values for that combination.

Within a single request, the combination of year, month, unitId, ledger, positionId, and partner must be unique. If the request contains duplicate combinations, the API rejects it with HTTP 409.

The API returns the following HTTP status codes:

Code	Meaning
`200`	The request was processed. An empty array (`[]`) means complete success. An array with entries means partial success: each returned entry contains an errorMessage that describes why the entry was rejected.
`401`	Authentication failed, for example because the API token is invalid.
`409`	The request contains duplicate combinations of year, month, unitId, ledger, positionId, and partner.
`500`	A server-side error occurred while saving the data.

json

The API returns the rejected entries, each with an errorMessage:

json

Cause: The API key is invalid, expired, or incorrectly formatted.

Solution:

Check that you copied the API key correctly from

Tax Administration

Make sure that the

Bearer

prefix precedes the key (on-premises/Azure mode).

Check that the API key is still active.

Generate a new API key if needed.

Cause: Validation errors in individual entries.

Solution:

Analyze the

errorMessage

fields in the response.

Correct the faulty entries.

Resend only the corrected entries, or all entries for the affected (

year

month

unitId

ledger

) combination.

Cause: A database error on the server side.

Solution:

Repeat the request after a short wait.

Contact support if the error recurs.

Check whether the data contains unusually large values or special characters.

Cause: The delete-insert logic deletes all existing entries for the (year, month, unitId, ledger) combination before each insert. Make sure that you send all entries for that combination together in a single request.

Overview

Important notes for integrators

Endpoint

Authentication

Request body

Required fields

Optional fields

Validation rules

Mandatory-field validation

Numeric validation

Format validation

Unique constraint

Technical limits and recommendations

Field length

Notes on the value field

The partner field and the unique constraint

String trimming and special characters

Import behavior

Response codes

Complete success (200)

Partial success (200)

Authentication failed (401)

Duplicate entries (409)

Server error (500)

Troubleshooting

"Invalid api key" (HTTP 401)

Some entries failed

"Error while saving data" (HTTP 500)

Data is overwritten or lost when batching

Table of Contents

Company

Legal Notice

Table of Contents

Related Articles

Company

Legal Notice