FreeFinance REST API

While a user authorizes itself against the API, it is not the organizational entity that holds all the data. A bookkeeping instance (such as a company, rent and leasing, or a freelancer) is represented as a client. A single user has access to one or several clients, and one client can be accessed by one or several users. Each user has one or more assigned roles for a client, which define the permissions the user has for that client. The initially created user might have all permissions available, while a special employee user might only be able to access specific modules.

For testing purposes, we offer two environments to develop against which are separated from production environments:

Once your application integration is ready for production, you can set the URL to the production environment, which depends on the specific portal of your user. Different portals exist for different partnerships, but for convenience every region (Austria, Germany, International, and so on, distinguished by a different top-level domain) has a single API URL. For example, the production URL https://app.freefinance.at in the Austrian region has many Austrian sub-portals, but the URL https://api.freefinance.at is available for users in all portals in the Austrian region. This allows application developers to use the API regardless of the specific portal of the user.
The same is true for https://app.freefinance.de and https://api.freefinance.de, and so on.

A user with the permission to connect external accounts to a client can create a technical user for that client. This is a separate, special user with its own fixed role tied to the client, and comes with a set of API client credentials to authenticate directly.

This approach is recommended in the following cases:

This approach is not recommended in these cases:

A technical user can be created in the web UI:
Navigate to My profile → User & Permission → Connected devices and choose the "Create technical user" option in the sidebar.

You will be given an API client id and API client secret. Store them responsibly like you would a password - they grant access to your client with all the permissions given to the "API user" role. If possible, restrict the permissions of that user to the minimum required for your use case.

To change the permissions of the API user, you can use the UI and navigate to My Profile → User & Permission → Permissions and select the Technical User role. Revoke all permissions not needed for your use case.

You can now obtain a valid token from the IDP, which is a different URL than the API URL. You can request the IDP URL from the API by calling /auth/issuer, and then appending the OIDC path (/protocol/openid-connect/token) to the returned URL for the full path.

The payload is in URl-encoded form with parameters as key-value pairs separated by "&". Supply your API client ID (client_id) and secret (client_secret) this way, and the grant_type set to the fixed value client_credentials.

When the access token expires (see the expires_in value in seconds, typically 5 minutes), you can simply issue a new token with the same credentials. A refresh token is not necessary and not provided.

Using this token, you can now issue API calls as the technical user and are bound by the permissions of its "API user" role.

By redirecting to our IDP with an authorization request, a user can safely log in on the trusted IDP and authorize your application to access the API. The returned authorization code can then be exchanged for an access token and refresh token.

This approach is recommended in the following cases:

The approach is not recommended if only a single client needs to be accessed. Creating a technical user is more straightforward and doesn’t require URL redirects.

Your application must be able to either store a secret safely server-side (for web applications with a back-end issuing the API calls) or implement the PKCE method to ensure that the authorization code is not intercepted. The API client must be created first, so contact us and provide the following information:

Once the API client is created and ready, you can begin the authorization process by redirecting the user of your application to the IDP, as returned by the /auth/issuer resource, and the OIDC path (/protocol/openid-connect/auth). You provide the following information as query parameters to that redirect:

The browser will be redirected to log in with the IDP and give consent to grant your application access. If consent is granted, the browser is redirected back to the redirect URL you provider with two query parameters: code and state.

You can then exchange the code for tokens with a POST request. The grant_type is set to the fixed value authorization_code, and the exact redirect URL used in the original redirect request must be provided.

If you have been issued an API client secret, pass it as client_secret instead of the code_verifier.

If the code and either the secret or the PKCE challenge is verified, you are returned an access_token and request_token.

Observe the expires_in value (in seconds) for the access_token and the refresh_token_expires_in value for the refresh_token. If you requested the offline_access scope, your refresh token will be valid for a long time (30 days).

You can use the access_token for the Bearer authorization in your API calls, and request a new token after it expires with your refresh_token.

As before, if you have been issued an API client secret, pass it as an additional client_secret parameter.

The API is divided into sections that correspond to feature groups or modules in Freefinance. Each module has a short, three-letter abbreviation and its corresponding tag in the OpenAPI definition file. The descriptions of the tags describe the module, and some modules are further divided by subtags for readability (such as CBI-INC and CBI-OUT for cash based invoicing, divided into incoming and outgoing invoices).

The base API endpoint path is /api/2.0/, usually followed by the three-letter module abbreviation and the resource.
GET <host>/api/2.0/fnd/countries for example would return all countries available in the API. FND refers to the foundation module, which represents basic countries, regions, currencies, and units of measure that can be used in the API.

To obtain all available clients, the /clients endpoint is available. It lists the numerical ID for a client, which is part of the resource path for all resources pertaining to that client. For example, the GET call would return a client with ID 10000, and to list all customers of that client, the path would look like this:
GET /clients/10000/mas/customers
Note that the module prefix is still part of the path after the client ID - the vast majority of resources are sub-paths of a client.

The API uses JSON as primary exchange format.
Property keys use snake case, such as unit_of_measure, for readability.

Resources that return files, like /pdf, exporters, and image endpoints return the proper file type. For uploads with sidecar json metadata, the API supports multipart requests (recommended) or having the attachment encoded as base64 inside a json property.

Date values are expected and returned in ISO format, such as "invoice_date": "2024-03-18" or "date_time": "2025-07-29T17:18:40.2161948". IDs for resources and references are UUIDs, with a few exceptions, such as client IDs (integers).

Most endpoints that return lists are sliced, which means that only a partial response is returned if the total result count exceeds the limit for a single response. They have the following format:

If the total_count exceeds the number of objects in the array, the next page can be returned by including the offset query parameter. For our previous example of fetching the customers of a client, the call would look like this:
GET /clients/10000/mas/customers?offset=100.

Most resources have a default result size of 100. By passing the limit parameter, that size can be adjusted to a maximum of 500. For example, customers no. 100-300 can be fetched with this URL:
GET /clients/10000/mas/customers?limit=200&offset=100.

If a resource has different limits, it will be noted in its documentation.

Depending on the resource, results can be sorted in the backend by passing the sort query parameter. Multiple sort parameters can be defined for nested sorting with a comma delimiter, and the sort order can be defined per property with the :ASC and :DESC suffixes. If no suffix is provided, the property is sorted in ascending order.

There is no standardized way to document sort parameters in the OpenAPI spec, you’ll have to refer to the documentation of a specific endpoint. In general, the major properties such as dates, totals, names etc. are sortable by passing the response property name, such as total. If a sort field is not recognized, it will be ignored.

Here is an example for sorting over multiple properties when querying the suppliers of a client:
GET /clients/10000/mas/suppliers?sort=display_name:ASC,supplier_number:DESC,zip_code

There is no support in the OpenAPI specification for indicating which properties of a particular resource can be sorted by, so no documented lists can be provided in a standardized way. Usually, the most important properties of the object can be used as sort parameter, and resources may have a default sort order if none is provided as parameter.

Many of the entities exposed in the API have references to other entities. For example, a customer of a client belongs to a country and region, which are given as reference.

The vast majority of entities use a UUID as identifier given in the id property, and are referenced with that UUID.

For responses, that reference is a nested object that contains not only the id itself, but also the most important data related to that reference. This is done to ease the readability of responses and include enough data that the reference can be shown in a meaningful way. There is no need for chains of API GET calls to get the basic information of a referenced entity.

As an example, a customer of a client can reference a contra_account, which is the default receivables contra account used in double-entry accounting invoices. The response format with the reference looks like this:

When creating or modifying an existing customer, the contra_account is referenced only by the ID of a valid account. The entire nested account object is not required and not part of the request schema. You don’t need to pass null for optional properties, it is equivalent to simply omitting it from the request.

In case a query parameter accepts multiple values at once, the values can be given as comma-separated list, or by adding the query parameter multiple times. For example, the endpoint
GET /clients/10000/pos/cash_registers
accepts an optional query parameter states to find cash registers that have any of the given states. To retrieve all cash registers that are either active or locked, the parameter can be set in the following ways:
GET /clients/10000/pos/cash_registers?states=ACTIVE,LOCKED
or
GET /clients/10000/pos/cash_registers?states=ACTIVE&states=LOCKED

This OR-logic is the default for querying over multiple possible values. If the resource uses AND-logic for that particular property, it will be stated in the description of the parameter.

If a request fails for validation or business logic related reasons, the error response has this format:

The application also uses these error codes:

As explained in the introduction, the client is the organizational entity that holds a bookkeeping instance. It is included in most API calls as a path parameter, so the first step of using the API is to query your available clients and select one for subsequent API requests.

Once you have successfully authenticated (see the Authentication section), you can call the GET clients API:

Most users will have only one client available. If you only ever need to access one specific client, you can store the ID permanently, as it does not change, and don’t need to query your available clients.

With the numerical ID of the client you can now make API calls within the context of that client by prepending clients/{id} to the actual resource. Here is an example to query the bookkeeping accounts of your client with the cbs/accounts API:

This example demonstrates the v2 API features outlined in the previous chapter:

The main use case of the API is to create invoices and bookings of some kind - like creating a new invoice for a customer. As these invoices are then included in the bookkeeping, the lines they contain must include an account and one or several tax class entries.

The combination of these two is required for every invoice line and receipt line you create. They can either be supplied directly, or defaulted by storing them in an item, and referencing that item in a line with defaulting enabled.
Either way, you have to give a valid combination of account and tax class entry at least once - either with the API here, or by setting them up in the UI for your items beforehand.

If you wish to supply them with the API, please continue with the examples in this chapter.

This section introduces the creation of CBI invoices, one of the most used features of the API. Before you jump in, make sure you have read the bookkeeping essentials.

Incoming and outgoing invoices are the primary method of creating bookkeeping incomes and expenses. Two types exist: incoming invoices define expenses, and outgoing invoices define incomes.

An invoice may have none, one or several bookings, and each booking in turn has a journal. Journals are realized incomes and outgos and created implicitly by the backend when required.

Payment works differently depending on the type of your bookkeeping registered with the client - see the following sections for details.

Items are part of the master data of a client, they are reusable definitions of a revenue line used in INV invoices and cash receipts. For use in the API, creating items beforehand (with accounts, tax class entries, prices and descriptions already included) allows you to create invoices and receipts quickly by referencing an item and enabling item defaulting. Alternatively, if you want to have complete control over the data of the line, you can take the values of the items and apply them to invoice and receipt lines yourself.

This section introduces the creation of invoices, one of the most used features of the API. Before you jump in, make sure you have read the bookkeeping essentials and optionally the item API.

Make sure not to confuse the invoicing from the INV feature (see the INV tag in the OpenAPI spec) with outgoing invoices from the CBI module (the CBI-OUT tag). CBI outgoing invoices are a simpler version only used for bookkeeping, while the INV module is more extensive with features like the PDF generation, per-line discounts, etc.

In general, you use the CBI module to track invoices created somewhere else, while you can use INV to create invoices in FreeFinance itself. Clients can use both modules concurrently for different use cases, but most users only require one or the other.

Invoices, along with all other document types from the invoicing module (offers, delivery notes, etc.) can be created in two major states: Staging documents are in a draft mode and can be freely edited and changed. Once a document is finalized, all corresponding documents are generated (PDF, XML) and further edits are restricted.

With this API you can upload files (PDF, XML and images) to the staging folder of the client. The files are then available in the My Invoices → Posting by PDF/File view of the application, which allows creating incoming/outgoing invoices and rebooks with them.

When uploading a PDF file or image, the built-in OCR detection feature extracts key information like the date, invoice amount, supplier etc. from it. This metadata is then used for suggestions when creating invoices.

For example, if the VAT number of a supplier is found, the suppliers in your master data are queried for a supplier with such a number. The invoice total is defaulted as amount, and so on. The list of known metadata keys in the OpenAPI specification shows you what kind of information can be extracted.

While the API also allows adding a list of metadata to the upload with well-known keys, custom metadata is ignored by the application to prevent inconsistent behavior and errors due to faulty data. If you don’t need the OCR detection feature and want to provide metadata yourself, contact us to mark your application as trusted.

Well-known XML formats like X-Invoice are parsed automatically. The same is true if a PDF has an embedded XML - OCR is skipped and the XML data has priority.