Documentation

Major changes

Inactive clients may be filtered out via optional parameter.
Tax year, folder ID, and the new field "source" are mandatory parameters. Source can be any text (should be your company's name and/or the product name).
Folders (formerly named categories), including the root folder ("Unsorted documents"), have a unique ID across all clients and tax years.
Tax years are no longer automatically created per client for the whole range (2016 to next calendar year). Rather, tax years must be initialized once per client before documents can be uploaded.
Upload is synchronous.

FAQ

Display OpenAPI file

Due to occasional inconsistencies in the display of the API reference, we recommend to download the OpenAPI document and display it in your local IDE, GitLab or Swagger Editor. We are currently working on a fix.

my-tax:income-tax-documents API in a nutshell

Digital documents are transferred to an income tax client in DATEV Meine Steuern, using the API my-tax:income-tax-documents.

A document consists of a binary file and corresponding metadata.
Documents are uploaded to a specific client, tax year, and folder.
Tax years must be initialized once per client. Example: tax year 2017 must once be created for client A. Use endpoint createIncomeTaxYear.
Every folder has a unique ID.
The upload process is synchronous.

Sample process/sequence of API calls

#	When (Frequency)	What (Purpose)	API Call
1	fixed time interval / on user action	Get and cache list of available clients	getClients
2	on user action	select client	n/a
3	on user action	get available tax years for income tax for the selected client	getIncomeTaxYears
4	on user action	if required: create new income tax year	createIncomeTaxYear (use getIncomeTaxYears to retrieve missing tax years for the selected client)
5	on user action	select income tax year	n/a
6	on user action	get available folders for client and income tax year	getIncomeTaxFolders
7	on user action	select folder	n/a
8	on user action	upload document, metadata to client, tax year, folder	saveIncomeTaxDocument

Clients

Using the endpoint getClients, you may query all available clients.

This will return ALL Meine Steuern-clients that the current user/access medium has permissions for. With the optional parameter "hide-inactive-omd-clients", you may filter for active clients only. Note that this will work ONLY if "DATEV Basisdaten Online" has been executed. Without "DATEV Basisdaten Online", inactive clients WILL continue to appear in the search result.

For further information on DATEV Basisdaten Online, see Basisdaten online für die DATEV-Cloud bereitstellen.
For further information on active vs inactive clients, see Mandanten inaktiv setzen.

Document

A document in DATEV Meine Steuern consists of a binary file and a metadata object.

Binary file

Files in DATEV Meine Steuern must meet the following criteria.

File types

Only the following file types are supported: PDF, TIF, TIFF, JPG, JPEG, PNG, TXT, CSV, DOCX, XLSX.

File size

File size must not exceed 100 MB.

Metadata

The following metadata can be attributed to documents in DATEV Meine Steuern, income tax.

Client ID

Mandatory.

Each document belongs to a specific client.

Tax year

Mandatory.

Valid range for tax years is [2016; calendar year + 1]). Example: 2022. Query existing and missing tax years per client ID via endpoint getIncomeTaxYears.

A specific tax year is not guaranteed to exist in a specific client. Check first via endpoint getIncomeTaxYears.

Folder ID

Mandatory.

A unique ID per folder (UUID). Query per combination client ID/tax year via endpoint getIncomeTaxFolders.

Source

Mandatory.

Source can be any text. Should be your company's name or the product name.

Note

Optional.

An optional note to the document, up to 1000 characters.

Sandbox

General Information

With the sandbox, you may simulate the various success and error response codes of the API endpoints.

Data set

The sandbox operates on a synthetic data set, so post operations will not result in actual change of data. The data set includes the following mock data for the various endpoints.

getClients: client ids 455148-100-100, 455148-200-200, ..., 455148-500-500.
getClient: same as getClients.
getIncomeTaxYears: For client id 455148-100-100, existing tax years and missing tax years 2018, 2019 (Sandbox reflects calendar year 2023).
getIncomeTaxFolders: For client id 455148-100-100, standard folders for all available tax years. Additionally, client and tax year-specific subfolders Investment1, Investment2 for tax year 2023 (parent folder: Investments).

Registration & Authorization

To use this API, you must have

a client that is registered for DATEV Meine Steuern and
sufficient permissions on your access medium to access that client (e.g., DATEV SmartCard or DATEV SmartLogin).

Registration

For information on how to register a client for DATEV Meine Steuern, see the following documents.

Authorization

For information on how to set up permissions to access a registered client for DATEV Meine Steuern, see the following documents.

Rechteverwaltung online: Rechte freischalten zur Nutzung von DATEV Meine Steuern

Client ID

Any registered client for DATEV Meine Steuern has a client ID which consists of three parts joined by "-".

Consultant number: 4 to 7 digits. Example: 1111
Client number: 1 to 5 digits. Example: 22222
Base number: 1 to 5 digits. Often but not necessarily identical to the client number. Example: 33333

Example

Example for a full client ID: 1111-22222-33333

Regex

^([1-9]\d{3,6})-([1-9]\d{0,4})-([1-9]\d{0,4}|0)$

Folders

Every folder has a unique ID.

From a business perspective, folders are divided into three types.
- Root folder ("Unsorted documents"),
- Standard folders (e.g., "Rentals", "Employee", "Children") and
- Subfolders (e.g., "House 1").
From a technical perspective, every folder has a unique ID: Rentals (client A; 2017) <> Rentals (client B: 2017) <> Rentals (client A: 2018). Use endpoint getIncomeTaxFolders to query available folders per client and tax year.
Subfolders must be created by the tax office for the client. Subfolders cannot be created either by the clients themselves, nor via this API (Exception: when creating a new tax year, all folders from the previous tax year, including subfolders, are created automatically).
Subfolders can only be created directly below a standard folder. There can be no subfolders on the same level as the standard folders, nor can there be nested subfolders.
Only the top-level folder Unsorted documents is guaranteed to exist for any client/tax year. Check first via endpoint getIncomeTaxFolders.

Folder Structure, Example

Client A

Client A, 2017	Client A, 2020	Client A, 2021	Client A, 2022
Unsorted documents (UUID H)	Unsorted documents (UUID A)	Unsorted documents (UUID E)	Unsorted documents (UUID I)
...	...	...	...
	Rentals (UUID B)	Rentals (UUID F)
	House 1 (UUID C)
	House 2 (UUID D)	House 2 (UUID G)
	...	...

Client B

Client B, 2019	Client A, 2021
Unsorted documents (UUID J)	Unsorted documents (UUID K)
...	...

List of standard folders

Note: With the exception of the top-level folder Unsorted documents, standard folders are not guaranteed to exist for any client/tax year. Check first via endpoint getIncomeTaxFolders.

Unsorted documents
Employee
Extraordinary expenses
Business/Self-employment
Services by contractors and household services
Investments
Children
Pensions
Special expenses/donations
Rentals
Insurance policies
Other income

References

For further information about the API, see the following documents.

	Link	Document	Description
1	[Terms_of_Use]	Interface Guidelines	Terms of use and prerequisites for using the API my-tax:documents, German equivalent to chapter Tasks for technical testing.
2	[OAuth]	Authentication for a data center	Describes how a data center can communicate with the DATEV data center via OAuth 2.0 and OpenID Connect.
3	[OAuth_mobile]	Authentication for mobile clients	Describes how mobile clients can communicate with the DATEV data center.
4	[1003606]	DATEV Help Center document no. 1003606	How to start with DATEV Meine Steuern.