API

invoiceR provides a REST interface with JSON. Every request needs authentication and runs with the permissions of the user the application logs in as.

The interfaces

invoiceR describes its endpoints in three OpenAPI documents:

Interface	For whom	Swagger UI	OpenAPI file
Public API	Applications of a tenant, for example a scanning service or your own portal	/docs/public	/docs/public.json
Management API	Partners who manage an installation (users, roles, master data, settings)	/docs/management	/docs/management.json
Internal API	Only for the invoiceR user interface. May change without notice.	/swagger

The paths are relative to the backend address, for example https://<server>/docs/public.

Caution

Only build integrations on endpoints of the Public API or the Management API. The internal API is not stable and changes with every version.

Opening the Swagger UI

The Swagger documentation shows all endpoints with parameters, examples and response schemas.

1. Open https://<server>/Ui/Login and log in with an invoiceR user.
2. The backend start page shows, among others, the links Öffentlich (Public API) and Management (Management API). Alternatively open https://<server>/docs/public or https://<server>/docs/management directly.

The user needs the permission Swagger UI (under Administration). Without it, invoiceR responds with status 403. If you are not logged in, it redirects you to the login page.

Note

In installations with several tenants, the permission Swagger UI is granted at host level. If you need the OpenAPI description as a tenant, contact support.

Public API

The Public API covers the life cycle of a document. The endpoints require the same permissions as the corresponding functions in the user interface:

Function	What it does	Required permission
Create document	Accepts an invoice as PDF and starts the workflow.	Tasks and Upload Document in Browser
Upload document	Stores a document with additional data (recognized text, selected form, free additional data as JSON) for import. Used for example for expenses from the mobile app.	Upload Document in Browser
Edit document	Changes an existing document.	Edit Task
Approve document	Gives approval for all lines of a document.	Give Approval
Reject document	Rejects all lines of a document with a reason.	Reject Approval
Proceed with workflow	Completes the open task of a document and moves it to the next step. Validations run as in the user interface.	Proceed invoice

You find the exact paths, methods and fields in the Swagger UI under /docs/public.

Management API

The Management API is meant for partners who look after an installation. Among other things it offers:

• Users and roles: query users and roles, change users, set the roles of a user.
• Master data: change existing accounts, suppliers and currencies.
• Approval levels: query approval levels and change their limits.
• Settings: read and write individual tenant settings.
• Version: query the installed version.

Every endpoint checks the matching permission, for example Master data for master data or user management for users and roles. Some endpoints (creating tenants, shutting down the system) are only intended for host operation.

Responses

Endpoints of the Public API and the Management API return the result directly as JSON, without the { "result": …, "success": … } envelope used by the internal API.

Error messages

If invoiceR cannot carry out a request, it responds with an HTTP error status.

You recognize business errors of invoiceR by the field isInvoiceR. The response looks like this:

{
  "isInvoiceR": true,
  "code": 500,
  "message": "Short description of the error",
  "type": "TaskLockedException",
  "details": "{\"taskId\":4711,\"taskExternalId\":\"R-000123\",\"isCurrentUser\":false,\"lockedByDisplayName\":\"Max Muster\",\"lockedOn\":\"2026-10-29T08:15:00\",\"canUnlockTask\":false}",
  "eventNames": []
}

Field	Meaning
isInvoiceR	Always true for invoiceR business errors.
code	Same value as the HTTP status. For today’s business errors this is usually 500.
type	Kind of error. Your application uses it to decide how to react.
details	Additional information about the error as JSON text. Its structure depends on type.
eventNames	Internal events triggered by the error. Usually empty.

The schemas of the error types and their details are part of the OpenAPI documents. Common types:

• TaskLockedException: Another user currently has the document open and locked. details names the task, who locks it, since when and whether the current user may remove the lock. Try again later.
• ValidationException: One or more validations failed, for example when proceeding with the workflow. details lists the failed validations. invoiceR discards changes made during validation.

You recognize all other errors (for example missing permission, invalid request, server error) by the HTTP status: 401 without valid login, 403 without permission, 400 for invalid data, 500 for an error on the server.