Skip to main content
API docs by Redocly

Tidely Partner API (2.7.0)

Download OpenAPI specification:Download

Introduction

Welcome to the Tidely Partner API v2. This API enables white-label partners to integrate with Tidely's financial planning and cash flow management platform on behalf of their customers.

Key Features

  • Financial Planning: Create and manage financial plans with flexible periods (daily, weekly, monthly)
  • Invoice Management: Import and sync invoices from external systems
  • Categories: Access and organize financial categories
  • Scenarios: Work with multiple financial scenarios for planning

Authentication

The Partner API uses OAuth 2.0 for authentication. Two flows are supported:

  • Authorization Code: For interactive applications where users authenticate directly
  • Client Credentials: For server-to-server integrations

Contact partnerships@tidely.com to obtain your client credentials.

Tenant Context

All Partner API requests require the X-Account-Id header to specify which customer account the request applies to. This allows partners to operate on behalf of multiple customers using a single set of credentials.

Support

For technical support, integration questions, or to report issues:

Authentication

Verify your credentials and check authentication status.

Verify token

Verifies that the authentication token is valid

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "name": "string"
}

Embedded Integration

Endpoints supporting the Embedded Integration: Obtain short-lived init tokens that log a Tidely user into the embedded Tidely frontend without showing them a login screen. See the Embedded Integration guide for the full flow, including the postMessage protocol between the parent page and the iframe.

Create SSO init token

Obtains a short-lived, single-use init token that the partner's frontend hands to the embedded Tidely iframe via postMessage. The Tidely frontend then exchanges the init token on Tidely's backend for a regular access + refresh token pair, logging the user in.

The init token is bound to the Tidely user identified by userId and to the account given via the X-Account-Id header. It expires after 30–60 seconds and cannot be reused once it has been exchanged.

See the Partner SSO guide for the full end-to-end flow.

Behaviour

  • Server-side only. This endpoint requires partner client credentials and must never be called from a browser.
  • One token per page load. Always obtain a fresh token when (re)loading the iframe; do not cache or pre-fetch.
  • Existing users only. Init tokens log existing users in. They do not create users — provision users via POST /users.

Error codes

Errors carry a stable, machine-readable code in the error field of the ExceptionDetails body so partners can react programmatically; message is a human-readable description (do not match on it):

HTTP error Meaning
400 INVALID_REQUEST Body malformed or userId missing/non-numeric.
400 MISSING_ACCOUNT_HEADER X-Account-Id header is missing.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 SSO_NOT_ENABLED The partner does not have the embedded SSO feature enabled.
404 USER_NOT_FOUND The userId does not exist, or the account/user is not accessible to the partner.
409 USER_INACTIVE The user exists but is disabled, deleted, or otherwise blocked from login.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
header Parameters
X-Account-Id
required
integer <int64>
Example: 12345

The unique identifier of the customer account to operate on. Required for all partner API requests.

Request Body schema: application/json
required
userId
required
integer <int64>

ID of the Tidely user to log in.

Responses

Request samples

Content type
application/json
{
  • "userId": 67890
}

Response samples

Content type
application/json
{
  • "initToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI2Nzg5MCIsImFjY291bnRJZCI6MTIzNDUsImlzcyI6Imh0dHBzOi8vYXV0aC50aWRlbHkuY29tIiwiYXVkIjoidGlkZWx5LWZyb250ZW5kIiwiaWF0IjoxNzMwOTk5OTk5LCJleHAiOjE3MzEwMDAwNTksImp0aSI6IjAxOTI4ZTUwLTAwMDAtNzAwMC04MDAwLWFiY2RlZjAxMjM0NSJ9.signature",
  • "expiresIn": 60,
  • "expiresAt": "2026-05-08T12:34:56Z"
}

Accounts

Manage customer accounts accessible by the partner. Accounts represent the end customers that the partner serves.

Create account

Creates a new account with a default company and an initial admin user.

Error codes

HTTP error Meaning
400 INVALID_REQUEST Request body is malformed or fails validation.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required account/write scope.
409 ACCOUNT_EXTERNAL_ID_ALREADY_EXISTS An account with the given externalId already exists for this partner.
409 USER_EMAIL_ALREADY_EXISTS The initial user's email address is already in use.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
Request Body schema: application/json
required
externalId
required
string

External identifier specified by the partner

companyName
required
string

Name of the main company to be created for this account

required
object (InitialUserCreateRequest)

Initial admin user created alongside a new account. Account/company are created implicitly and the role is ADMIN.

Responses

Request samples

Content type
application/json
{
  • "externalId": "partner-newclient-003",
  • "companyName": "New Client GmbH",
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Account created successfully",
  • "account": {
    },
  • "user": {
    },
  • "company": {
    }
}

Get accounts

Get all accounts accessible by the partner.

Error codes

HTTP error Meaning
400 INVALID_REQUEST A query parameter is invalid.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required account/read scope.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
query Parameters
page
integer >= 0
Default: 0

Page number (0-based)

pageSize
integer [ 1 .. 1000 ]
Default: 50

Number of accounts per page

status
string
Enum: "ACTIVE" "IN_TRIAL" "CANCELLED" "NON_RENEWING"

Filter accounts by status

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Accounts retrieved successfully",
  • "number": 0,
  • "size": 20,
  • "totalElements": 125,
  • "totalPages": 8,
  • "data": [
    ]
}

Get account

Get account by id. Requires the X-Account-Id header.

Error codes

HTTP error Meaning
400 MISSING_ACCOUNT_HEADER X-Account-Id header is missing.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required account/read scope.
404 ACCOUNT_NOT_FOUND No account exists with the given id, or it is not accessible to the partner.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
path Parameters
id
required
integer <int64>

The ID of the account

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Account retrieved successfully",
  • "data": {
    }
}

Update account

Partially updates an account. Only the company name is currently partner-mutable. Requires the X-Account-Id header.

Error codes

HTTP error Meaning
400 INVALID_REQUEST Request body is malformed or fails validation.
400 MISSING_ACCOUNT_HEADER X-Account-Id header is missing.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required account/write scope.
404 ACCOUNT_NOT_FOUND No account exists with the given id, or it is not accessible to the partner.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
path Parameters
id
required
integer <int64>

The ID of the account

Request Body schema: application/json
required
companyName
string

New name for the account's main company

Responses

Request samples

Content type
application/json
{
  • "companyName": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Account updated successfully",
  • "data": {
    }
}

Delete account

Deletes account by id. Requires the X-Account-Id header.

Error codes

HTTP error Meaning
400 MISSING_ACCOUNT_HEADER X-Account-Id header is missing.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required account/write scope.
404 ACCOUNT_NOT_FOUND No account exists with the given id, or it is not accessible to the partner.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
path Parameters
id
required
integer <int64>

The ID of the account

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Account deleted successfully",
  • "id": 12345
}

Companies

View companies.

Get companies

Get companies

query Parameters
page
integer >= 0
Default: 0

Page number (0-based)

pageSize
integer [ 1 .. 1000 ]
Default: 50

Number of balances per page

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Companies retrieved successfully",
  • "number": 0,
  • "size": 20,
  • "totalElements": 125,
  • "totalPages": 8,
  • "data": [
    ]
}

Get company

Get company by id

path Parameters
id
required
integer <int64>

The ID of the company

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Users

Manage users within customer accounts.

Create user

Creates a user in the specified account and company with the given role. Requires the X-Account-Id header.

Error codes

HTTP error Meaning
400 INVALID_REQUEST Request body is malformed or fails validation.
400 MISSING_ACCOUNT_HEADER X-Account-Id header is missing.
400 MAX_USERS_REACHED The account has reached the user limit for its current plan.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required user/write scope.
404 ACCOUNT_NOT_FOUND No account exists for the X-Account-Id header.
404 COMPANY_NOT_FOUND No company with the given companyId exists in the account.
409 USER_EXTERNAL_ID_ALREADY_EXISTS A user with the given externalId already exists in the account.
409 USER_EMAIL_ALREADY_EXISTS A user with the given email address already exists.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
header Parameters
X-Account-Id
required
integer <int64>
Example: 12345

The unique identifier of the customer account to operate on. Required for all partner API requests.

Request Body schema: application/json
required
companyId
required
integer <int64>

ID of the company within the account the user is placed in

role
required
string (UserRole)
Enum: "ADMIN" "USER" "CONTRIBUTOR" "INVESTOR"

Role granted to the user within the account/company

externalId
required
string

External identifier for the user specified by the partner

email
required
string <email>

Email address of the user

firstName
required
string

First name of the user

lastName
required
string

Last name of the user

language
string (UserLanguage)
Enum: "en-US" "de-DE"

Preferred UI language of the user.

Responses

Request samples

Content type
application/json
{
  • "companyId": 67890,
  • "role": "USER",
  • "externalId": "user-jane-002",
  • "email": "jane.smith@newclient.com",
  • "firstName": "Jane",
  • "lastName": "Smith"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User created successfully",
  • "data": {
    }
}

Get users

Lists users belonging to the specified account. Requires the X-Account-Id header.

Error codes

HTTP error Meaning
400 INVALID_REQUEST A query parameter is invalid.
400 MISSING_ACCOUNT_HEADER X-Account-Id header is missing.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required user/read scope.
404 ACCOUNT_NOT_FOUND No account exists for the X-Account-Id header, or it is not accessible to the partner.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
query Parameters
page
integer >= 0
Default: 0

Page number (0-based)

pageSize
integer [ 1 .. 1000 ]
Default: 50

Number of users per page

header Parameters
X-Account-Id
required
integer <int64>
Example: 12345

The unique identifier of the customer account to operate on. Required for all partner API requests.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Users retrieved successfully",
  • "number": 0,
  • "size": 50,
  • "totalElements": 2,
  • "totalPages": 1,
  • "data": [
    ]
}

Get user

Retrieve a specific user by id. Requires the X-Account-Id header.

Error codes

HTTP error Meaning
400 MISSING_ACCOUNT_HEADER X-Account-Id header is missing.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required user/read scope.
404 ACCOUNT_NOT_FOUND The account does not exist or is not accessible to the partner.
404 USER_NOT_FOUND No user exists with the given id in this account.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
path Parameters
userId
required
integer <int64>

The ID of the user

header Parameters
X-Account-Id
required
integer <int64>
Example: 12345

The unique identifier of the customer account to operate on. Required for all partner API requests.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User retrieved successfully",
  • "data": {
    }
}

Update user

Partially updates a user. Only firstName and lastName are currently partner-mutable. Requires the X-Account-Id header.

Error codes

HTTP error Meaning
400 INVALID_REQUEST Request body is malformed or fails validation.
400 MISSING_ACCOUNT_HEADER X-Account-Id header is missing.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required user/write scope.
404 ACCOUNT_NOT_FOUND The account does not exist or is not accessible to the partner.
404 USER_NOT_FOUND No user exists with the given id in this account.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
path Parameters
userId
required
integer <int64>

The ID of the user

header Parameters
X-Account-Id
required
integer <int64>
Example: 12345

The unique identifier of the customer account to operate on. Required for all partner API requests.

Request Body schema: application/json
required
firstName
string

First name of the user

lastName
string

Last name of the user

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User updated successfully",
  • "data": {
    }
}

Delete user

Deletes a user. Requires the X-Account-Id header.

Error codes

HTTP error Meaning
400 MISSING_ACCOUNT_HEADER X-Account-Id header is missing.
401 INVALID_CREDENTIALS Partner access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required user/write scope.
404 ACCOUNT_NOT_FOUND The account does not exist or is not accessible to the partner.
404 USER_NOT_FOUND No user exists with the given id in this account.
409 USER_CANNOT_BE_DELETED The user is the only remaining user in the account.
409 LAST_ADMIN_CANNOT_BE_DELETED The user is the only remaining admin in the account.
500 INTERNAL_ERROR Unexpected server error.
Authorizations:
OAuth2
path Parameters
userId
required
integer <int64>

The ID of the user

header Parameters
X-Account-Id
required
integer <int64>
Example: 12345

The unique identifier of the customer account to operate on. Required for all partner API requests.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User deleted successfully",
  • "id": 56789
}

Categories

Retrieve financial categories for organizing transactions and plans. Categories are hierarchical and classified by type (income/expense, operational/investment/financing).

Get categories

Retrieves all categories for the authenticated user

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create category

Creates a new financial category, type is ignored if parentId is specified

Request Body schema: application/json
required
name
required
string

Name of the category

type
required
string (CategoryType)
Enum: "INCOME_OPERATIONAL" "INCOME_INVESTMENT" "INCOME_FINANCING" "EXPENSE_OPERATIONAL" "EXPENSE_INVESTMENT" "EXPENSE_FINANCING"

Type of category indicating income or expense classification

parentId
integer or null <int64>

ID of the parent category for hierarchical categorization

Responses

Request samples

Content type
application/json
{
  • "name": "E-Commerce Revenue",
  • "type": "INCOME_OPERATIONAL",
  • "parentId": 100
}

Response samples

Content type
application/json
{
  • "id": 123,
  • "name": "E-Commerce Revenue",
  • "type": "INCOME_OPERATIONAL",
  • "parentId": 100,
  • "enabledForPlannedTransactions": true
}

Get category

Retrieves a single category by ID

path Parameters
id
required
integer <int64>

The ID of the category

Responses

Response samples

Content type
application/json
{
  • "id": 123,
  • "name": "E-Commerce Revenue",
  • "type": "INCOME_OPERATIONAL",
  • "parentId": 100,
  • "enabledForPlannedTransactions": true
}

Update category

Updates an existing category

path Parameters
id
required
integer <int64>

The ID of the category

Request Body schema: application/json
required
name
string

Name of the category

type
string (CategoryType)
Enum: "INCOME_OPERATIONAL" "INCOME_INVESTMENT" "INCOME_FINANCING" "EXPENSE_OPERATIONAL" "EXPENSE_INVESTMENT" "EXPENSE_FINANCING"

Type of category indicating income or expense classification

Responses

Request samples

Content type
application/json
{
  • "name": "E-Commerce Revenue Updated",
  • "type": "INCOME_OPERATIONAL"
}

Response samples

Content type
application/json
{
  • "id": 123,
  • "name": "E-Commerce Revenue Updated",
  • "type": "INCOME_OPERATIONAL",
  • "parentId": 100,
  • "enabledForPlannedTransactions": true
}

Delete category

Deletes a category by ID

path Parameters
id
required
integer <int64>

The ID of the category

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "id": 0
}

Plans

Create, update, and delete financial plans for cash flow forecasting. Plans can be created for different periods (daily, weekly, monthly) and scenarios. Supports both single and bulk plan creation.

Create plan

Creates a new financial plan for a specific category and scenario

Request Body schema: application/json
required
categoryId
integer <int64>

Unique identifier of the category. If neither categoryId nor categoryName is specified, plan will go to uncategorized expenses for negative amounts and uncategorized income for positive amounts.

categoryName
string

Category path as a string (e.g., 'Einzahlungen aus Geschäftstätigkeit->E-COMMERCE->Plattform 1'). Used if categoryId is not provided.

amount
required
number [ -10000000000000000 .. 10000000000000000 ]

Amount of the plan (negative for expenses, positive for income)

period
required
string
Enum: "DAILY" "WEEKLY" "MONTHLY"

Period for which the plan value applies

date
required
string <date>

The date of the plan in ISO 8601 format (yyyy-MM-dd). For MONTHLY period, use the first day of the month. For WEEKLY period, use the first day of the week.

type
required
string
Value: "ONE_TIME"

Type of the plan

name
required
string [ 1 .. 100 ] characters

Name of the plan

scenarioId
integer <int64>

Identifier of the scenario. If not specified, the plan will be created for the Base scenario.

scenarioName
string

Name of the scenario. Used if scenarioId is not provided. If neither is specified, the Base scenario is used.

replaceCurrentValuesForThePeriod
boolean
Default: false

If true, replaces existing values for the period. If false, adds to existing values.

Responses

Request samples

Content type
application/json
{
  • "categoryId": 123,
  • "amount": 5000,
  • "period": "MONTHLY",
  • "date": "2024-10-01",
  • "type": "ONE_TIME",
  • "name": "October Revenue Plan",
  • "scenarioId": 1,
  • "replaceCurrentValuesForThePeriod": false
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "planId": 0
}

Delete plans

Deletes all plans for a specific category and scenario combination

query Parameters
categoryId
required
integer <int64>
Example: categoryId=123

The ID of the category

scenarioId
required
integer <int64>
Example: scenarioId=1

The ID of the scenario

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "deletedCount": 0
}

Create multiple plans

Creates multiple financial plans in a single request

Request Body schema: application/json
required
Array
categoryId
integer <int64>

Unique identifier of the category. If neither categoryId nor categoryName is specified, plan will go to uncategorized expenses for negative amounts and uncategorized income for positive amounts.

categoryName
string

Category path as a string (e.g., 'Einzahlungen aus Geschäftstätigkeit->E-COMMERCE->Plattform 1'). Used if categoryId is not provided.

amount
required
number [ -10000000000000000 .. 10000000000000000 ]

Amount of the plan (negative for expenses, positive for income)

period
required
string
Enum: "DAILY" "WEEKLY" "MONTHLY"

Period for which the plan value applies

date
required
string <date>

The date of the plan in ISO 8601 format (yyyy-MM-dd). For MONTHLY period, use the first day of the month. For WEEKLY period, use the first day of the week.

type
required
string
Value: "ONE_TIME"

Type of the plan

name
required
string [ 1 .. 100 ] characters

Name of the plan

scenarioId
integer <int64>

Identifier of the scenario. If not specified, the plan will be created for the Base scenario.

scenarioName
string

Name of the scenario. Used if scenarioId is not provided. If neither is specified, the Base scenario is used.

replaceCurrentValuesForThePeriod
boolean
Default: false

If true, replaces existing values for the period. If false, adds to existing values.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "createdCount": 0,
  • "planIds": [
    ]
}

Invoices

Import invoices from external systems into Tidely. Supports sales invoices, purchase invoices, and credit notes. Automatically categorizes and integrates with cash flow planning.

Get invoices

Get all invoices

query Parameters
invoiceTypeFilter
required
string (InvoiceTypeFilter)
Enum: "SALE" "PURCHASE"

Type of invoices to retrieve

externalId
Array of strings <= 100 items [ items <= 255 characters ]

Filter invoices by external identifier. Repeat the parameter to filter by multiple external IDs (e.g. ?externalId=INV-001&externalId=INV-002). Limited to 100 values per request to avoid exceeding URL length limits.

page
integer >= 0
Default: 0

Page number (0-based)

pageSize
integer [ 1 .. 1000 ]
Default: 50

Number of invoices per page

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Invoices retrieved successfully",
  • "number": 0,
  • "size": 50,
  • "totalElements": 2,
  • "totalPages": 1,
  • "data": [
    ]
}

Create invoice

Creates a new invoice

Request Body schema: application/json
required
invoiceDate
string <date>

Invoice date in ISO 8601 format

dueDate
string <date>

Due date of the invoice in ISO 8601 format

paidDate
string or null <date>

Invoice payment date and time in ISO 8601 format

invoiceNumber
required
string non-empty

Invoice number

contactName
required
string non-empty

Recipient name of the invoice

totalGrossAmount
required
number [ -10000000000000000 .. 10000000000000000 ]

Total gross amount including tax

invoiceStatus
string
Enum: "DRAFT" "OPEN" "PAID" "PARTIALLY_PAID" "CANCELED" "WITHHELD" "OFFER" "ORDER" "PLANNED" "RELEASED"

Status of the invoice

openAmount
number or null [ -10000000000000000 .. 10000000000000000 ]

Open (unpaid) amount of the invoice

note
string or null

Description or notes for the invoice

categoryId
integer or null <int64>

Unique identifier of the category

externalId
string

External identifier of the invoice, used for integration with external systems

invoiceType
required
string (InvoiceTypeEnum)
Enum: "SALES_INVOICE" "SALES_CREDIT_NOTE" "PURCHASE_INVOICE" "PURCHASE_CREDIT_NOTE"

Type of invoice

Responses

Request samples

Content type
application/json
{
  • "externalId": "INV-2024-001",
  • "invoiceDate": "2024-10-15",
  • "dueDate": "2024-11-15",
  • "invoiceNumber": "2024-001",
  • "contactName": "ACME Corp",
  • "invoiceType": "SALES_INVOICE",
  • "totalGrossAmount": 11900,
  • "openAmount": 11900,
  • "invoiceStatus": "OPEN"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Create multiple invoices

Creates multiple invoices in a single request. A maximum of 1000 invoices per request is allowed. Requests exceeding this limit will be rejected with a 400 Bad Request response.

Request Body schema: application/json
required
required
Array of objects (InvoiceCreateRequest) [ 1 .. 1000 ] items
Array ([ 1 .. 1000 ] items)
invoiceDate
string <date>

Invoice date in ISO 8601 format

dueDate
string <date>

Due date of the invoice in ISO 8601 format

paidDate
string or null <date>

Invoice payment date and time in ISO 8601 format

invoiceNumber
required
string non-empty

Invoice number

contactName
required
string non-empty

Recipient name of the invoice

totalGrossAmount
required
number [ -10000000000000000 .. 10000000000000000 ]

Total gross amount including tax

invoiceStatus
string
Enum: "DRAFT" "OPEN" "PAID" "PARTIALLY_PAID" "CANCELED" "WITHHELD" "OFFER" "ORDER" "PLANNED" "RELEASED"

Status of the invoice

openAmount
number or null [ -10000000000000000 .. 10000000000000000 ]

Open (unpaid) amount of the invoice

note
string or null

Description or notes for the invoice

categoryId
integer or null <int64>

Unique identifier of the category

externalId
string

External identifier of the invoice, used for integration with external systems

invoiceType
required
string (InvoiceTypeEnum)
Enum: "SALES_INVOICE" "SALES_CREDIT_NOTE" "PURCHASE_INVOICE" "PURCHASE_CREDIT_NOTE"

Type of invoice

Responses

Request samples

Content type
application/json
{
  • "invoices": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "createdCount": 0,
  • "invoiceIds": [
    ],
  • "failedCount": 0,
  • "errors": [
    ]
}

Get invoice

Get invoice by id

path Parameters
id
required
integer <int64>

The ID of the invoice

query Parameters
invoiceTypeFilter
required
string (InvoiceTypeFilter)
Enum: "SALE" "PURCHASE"

Type of invoices to retrieve

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Update invoice

Updates an invoice. Invoices that originate from an ERP integration are read-only — update and delete operations are not allowed.

path Parameters
id
required
integer <int64>

The ID of the invoice

query Parameters
invoiceTypeFilter
required
string (InvoiceTypeFilter)
Enum: "SALE" "PURCHASE"

Type of invoices to retrieve

Request Body schema: application/json
required
invoiceDate
string <date>

Invoice date in ISO 8601 format

dueDate
string <date>

Due date of the invoice in ISO 8601 format

paidDate
string or null <date>

Invoice payment date and time in ISO 8601 format

invoiceNumber
string non-empty

Invoice number

contactName
string non-empty

Recipient name of the invoice

totalGrossAmount
number [ -10000000000000000 .. 10000000000000000 ]

Total gross amount including tax

invoiceStatus
string
Enum: "DRAFT" "OPEN" "PAID" "PARTIALLY_PAID" "CANCELED" "WITHHELD" "OFFER" "ORDER" "PLANNED" "RELEASED"

Status of the invoice

openAmount
number or null [ -10000000000000000 .. 10000000000000000 ]

Open (unpaid) amount of the invoice

note
string or null

Description or notes for the invoice

categoryId
integer or null <int64>

Unique identifier of the category

Responses

Request samples

Content type
application/json
{
  • "invoiceDate": "2024-10-15",
  • "dueDate": "2024-11-15",
  • "invoiceNumber": "2024-001",
  • "contactName": "ACME Corp",
  • "totalGrossAmount": 11900,
  • "openAmount": 11900,
  • "invoiceStatus": "PAID",
  • "currency": "EUR",
  • "paidDate": "2024-11-10"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Delete invoice

Deletes an invoice by id. Invoices that originate from an ERP integration are read-only — update and delete operations are not allowed.

path Parameters
id
required
integer <int64>

The ID of the invoice

query Parameters
invoiceTypeFilter
required
string (InvoiceTypeFilter)
Enum: "SALE" "PURCHASE"

Type of invoices to retrieve

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "id": 0
}

Scenarios

Access financial planning scenarios for what-if analysis. Each account has a base scenario and can create additional scenarios for comparison.

Get scenarios

Retrieves all scenarios for the authenticated user

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get scenario

Retrieves a single scenario by its ID

path Parameters
scenarioId
required
integer <int64>
Example: 1

The ID of the scenario to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "isBaseCase": true
}

Bank Accounts

View and manage bank accounts.

Get bank accounts

Get all bank accounts

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Bank accounts retrieved successfully",
  • "data": [
    ]
}

Create bank account

Creates a new bank account. The account counts towards the subscription's bank-account limit.

Error codes

HTTP error Meaning
400 INVALID_REQUEST Request body is malformed or fails validation.
400 MAX_BANK_ACCOUNTS_REACHED The subscription's bank-account limit has been reached.
401 INVALID_CREDENTIALS Access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required scope.
404 COMPANY_NOT_FOUND The referenced company does not exist or is not accessible.
500 INTERNAL_ERROR Unexpected server error.
Request Body schema: application/json
required
companyId
integer <int64>

ID of the company the bank account belongs to

iban
string

International Bank Account Number

accountNumber
string

Local account number

accountCurrency
required
string (Currency)
Default: "EUR"
Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTC" "BTN" "BWP" "BYR" "BYN" "BZD" "CAD" "CDF" "CHE" "CHF" "CHN" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GGP" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "IMP" "INR" "IQD" "IRR" "ISK" "JEP" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KID" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NIS" "NOK" "NPR" "NTD" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PRB" "PYG" "QAR" "RMB" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SLS" "SOS" "SRD" "SSP" "STD" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TVD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UYW" "UZS" "VEF" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMK" "ZMW" "ZWB" "ZWL"

ISO 4217 currency codes

accountName
required
string

Name of the account

bankName
required
string <= 255 characters

Bank of the account

balanceReference
number [ -1000000000000 .. 1000000000000 ]

Start-of-day balance of the bank account on the date specified in balanceDate. This balance will be used as a reference for calculating past and future balances based on the bank account's transactions.

balanceDate
string <date>

The date of the balance specified in balanceReference in ISO 8601 format (yyyy-MM-dd).

accountType
required
string (AccountType)
Enum: "CHECKING" "SAVINGS" "CREDITCARD" "SECURITY" "LOAN" "POCKET" "MEMBERSHIP" "BAUSPAREN"

Type of account

externalId
string

External identifier for the bank account, used for integration with external systems

visible
boolean

Whether the bank account is visible and active. Defaults to true. When false the account is disabled: it stops counting towards the subscription bank-account limit and is hidden from cashflow. On create, set false to create the account already disabled. For partner-managed (PARTNER) accounts this is the only field the customer may change; all other fields are ignored.

Responses

Request samples

Content type
application/json
{
  • "externalId": "123",
  • "iban": "DE89370400440532013000",
  • "accountNumber": "1234567890",
  • "accountCurrency": "EUR",
  • "accountName": "Main Business Account",
  • "bankName": "Deutsche Bank",
  • "companyId": 1,
  • "accountType": "CHECKING",
  • "balanceReference": 2100,
  • "balanceDate": "2025-03-10"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Get bank account

Get bank account by id

path Parameters
id
required
integer <int64>

The ID of the bank account

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Update bank account

Updates a bank account.

A bank account may only be modified through the surface that manages its provider: the public API may modify API accounts, the partner API may modify PARTNER accounts. Requests targeting an account managed by another surface (e.g. an OFFLINE, ONLINE, or PARTNER account via the public API) are rejected with 409 BANK_ACCOUNT_NOT_MODIFIABLE. To manage an OFFLINE account through the public API, convert it to API first (see the convert endpoint).

Error codes

HTTP error Meaning
400 INVALID_REQUEST Request body is malformed or fails validation.
401 INVALID_CREDENTIALS Access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required scope.
404 BANK_ACCOUNT_NOT_FOUND The bank account does not exist or is not accessible.
409 BANK_ACCOUNT_NOT_MODIFIABLE The bank account is partner-managed and cannot be modified.
500 INTERNAL_ERROR Unexpected server error.
path Parameters
id
required
integer <int64>

The ID of the bank account

Request Body schema: application/json
required
companyId
integer <int64>

ID of the company the bank account belongs to

iban
string

International Bank Account Number

accountNumber
string

Local account number

accountCurrency
string (Currency)
Default: "EUR"
Enum: "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTC" "BTN" "BWP" "BYR" "BYN" "BZD" "CAD" "CDF" "CHE" "CHF" "CHN" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DKK" "DOP" "DZD" "EGP" "ERN" "ETB" "EUR" "FJD" "FKP" "GBP" "GEL" "GGP" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HRK" "HTG" "HUF" "IDR" "ILS" "IMP" "INR" "IQD" "IRR" "ISK" "JEP" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KID" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRO" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NIS" "NOK" "NPR" "NTD" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PRB" "PYG" "QAR" "RMB" "RON" "RSD" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SEK" "SGD" "SHP" "SLL" "SLS" "SOS" "SRD" "SSP" "STD" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TVD" "TWD" "TZS" "UAH" "UGX" "USD" "USN" "UYI" "UYU" "UYW" "UZS" "VEF" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMK" "ZMW" "ZWB" "ZWL"

ISO 4217 currency codes

accountName
string

Name of the account

bankName
string <= 255 characters

Bank of the account

balanceReference
number [ -1000000000000 .. 1000000000000 ]

Start-of-day balance of the bank account on the date specified in balanceDate. This balance will be used as a reference for calculating past and future balances based on the bank account's transactions.

balanceDate
string <date>

The date of the balance specified in balanceReference in ISO 8601 format (yyyy-MM-dd).

accountType
string (AccountType)
Enum: "CHECKING" "SAVINGS" "CREDITCARD" "SECURITY" "LOAN" "POCKET" "MEMBERSHIP" "BAUSPAREN"

Type of account

externalId
string

External identifier for the bank account, used for integration with external systems

visible
boolean

Whether the bank account is visible and active. Defaults to true. When false the account is disabled: it stops counting towards the subscription bank-account limit and is hidden from cashflow. On create, set false to create the account already disabled. For partner-managed (PARTNER) accounts this is the only field the customer may change; all other fields are ignored.

Responses

Request samples

Content type
application/json
{
  • "externalId": "123",
  • "iban": "DE89370400440532213000",
  • "accountNumber": "1234567890",
  • "accountCurrency": "EUR",
  • "accountName": "Test bank account",
  • "bankName": "Deutsche Bank",
  • "accountType": "CHECKING",
  • "balanceDate": "2026-03-11",
  • "companyId": 1,
  • "balanceReference": 2400
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Delete bank accounts

Deletes a bank account by id.

A bank account may only be deleted through the surface that manages its provider: the public API may delete API accounts, the partner API may delete PARTNER accounts. Requests targeting an account managed by another surface are rejected with 409 BANK_ACCOUNT_NOT_MODIFIABLE.

Error codes

HTTP error Meaning
401 INVALID_CREDENTIALS Access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required scope.
404 BANK_ACCOUNT_NOT_FOUND The bank account does not exist or is not accessible.
409 BANK_ACCOUNT_NOT_MODIFIABLE The bank account is partner-managed and cannot be deleted.
500 INTERNAL_ERROR Unexpected server error.
path Parameters
id
required
integer <int64>

The ID of the bank account

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "id": 0
}

Convert bank account provider

Converts a bank account between API (managed through the public API) and OFFLINE (managed manually). Only these two providers can be converted into one another — bank-synced (ONLINE) accounts and partner-managed (PARTNER) accounts cannot be converted.

A conversion into API makes the account count towards the subscription's bank account limit. An account can be converted at most once every 30 days.

Error codes

HTTP error Meaning
400 INVALID_REQUEST Request body is malformed or targetProvider is missing/invalid.
400 PROVIDER_CONVERSION_TOO_SOON The account can only be converted once every 30 days and was converted recently.
400 MAX_BANK_ACCOUNTS_REACHED Converting to API would exceed the subscription's bank-account limit.
401 INVALID_CREDENTIALS Access token missing, expired, or invalid.
403 INSUFFICIENT_SCOPE Access token lacks the required scope.
404 BANK_ACCOUNT_NOT_FOUND The bank account does not exist or is not accessible.
409 PROVIDER_CONVERSION_NOT_ALLOWED The account's current or target provider is not API/OFFLINE.
500 INTERNAL_ERROR Unexpected server error.
path Parameters
id
required
integer <int64>

The ID of the bank account

Request Body schema: application/json
required
targetProvider
required
string
Enum: "API" "OFFLINE"

The provider to convert the bank account to. Only conversions between API and OFFLINE are supported.

Responses

Request samples

Content type
application/json
{
  • "targetProvider": "OFFLINE"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Get bank account balances

Get all balances for a bank account

path Parameters
id
required
integer <int64>

ID of the bank account

query Parameters
page
integer >= 0
Default: 0

Page number (0-based)

pageSize
integer [ 1 .. 1000 ]
Default: 50

Number of balances per page

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Bank account balances retrieved successfully",
  • "number": 0,
  • "size": 20,
  • "totalElements": 125,
  • "totalPages": 8,
  • "data": [
    ]
}

Bank Account Transactions

View and manage bank account transactions.

Get bank account transactions

Get all bank account transactions

query Parameters
bankAccountId
required
integer <int64>

ID of the bank account to filter transactions

page
integer >= 0
Default: 0

Page number (0-based)

pageSize
integer [ 1 .. 1000 ]
Default: 50

Number of transactions per page

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Transactions retrieved successfully",
  • "number": 0,
  • "size": 20,
  • "totalElements": 125,
  • "totalPages": 8,
  • "data": [
    ]
}

Create bank account transaction

Creates a new bank account transaction.

Transactions may only be written to an account managed by the calling surface: the public API to API accounts, the partner API to PARTNER accounts. Writes targeting an account managed by another surface are rejected with 409 BANK_ACCOUNT_NOT_MODIFIABLE.

Request Body schema: application/json
required
bankAccountId
required
integer <int64>
required
object

Bank account transaction base model

Responses

Request samples

Content type
application/json
{
  • "bankAccountId": 10,
  • "transaction": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Create multiple bank account transactions

Creates multiple bank account transactions in a single request. A maximum of 1000 transactions per bank account entry is allowed per request. Requests exceeding this limit will be rejected with a 400 Bad Request response.

Transactions may only be written to an account managed by the calling surface: the public API to API accounts, the partner API to PARTNER accounts. Writes targeting an account managed by another surface are rejected with 409 BANK_ACCOUNT_NOT_MODIFIABLE.

Request Body schema: application/json
required
bankAccountId
required
integer <int64>
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "bankAccountId": 10,
  • "transactions": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "createdCount": 0,
  • "created": [
    ],
  • "failedCount": 0,
  • "errors": [
    ],
  • "skippedCount": 0,
  • "skipped": [
    ]
}

Check existence of bank account transactions by external ID

Checks whether transactions with the given external IDs already exist for a bank account. Useful for deduplication checks before a bulk create, or for inline reconciliation after a resend. A maximum of 1000 external IDs per request is allowed.

Request Body schema: application/json
required
bankAccountId
required
integer <int64>

ID of the bank account to check against

externalIds
required
Array of strings [ 1 .. 1000 ] items

External IDs to check

Responses

Request samples

Content type
application/json
{
  • "bankAccountId": 10,
  • "externalIds": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Get bank account transaction

Get bank account transaction by id

path Parameters
id
required
integer <int64>

The ID of the bank account transaction

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Update bank account transaction

Updates a bank account transaction.

A transaction may only be modified through the surface that manages its account's provider (public API for API accounts, partner API for PARTNER accounts). Requests targeting an account managed by another surface are rejected with 409 BANK_ACCOUNT_NOT_MODIFIABLE.

path Parameters
id
required
integer <int64>

The ID of the bank account transaction

Request Body schema: application/json
required
categoryId
integer <int64>

ID of the category

bookingDate
string <date>

Booking date in ISO 8601 format

amount
number [ -10000000000000000 .. 10000000000000000 ]

Transaction amount in bank account currency

counterpartName
string

Counterpart of the transaction

counterpartAccountNumber
string

Counterpart account number of the transaction

counterpartIban
string

Counterpart iban of the transaction

purpose
string

Description of the transaction

counterpartCustomerReference
string

Counterpart customer reference

externalId
string <= 255 characters

External identifier for the transaction, used for integration with external systems

Responses

Request samples

Content type
application/json
{
  • "categoryId": 5,
  • "externalId": "1234",
  • "bookingDate": "2024-10-15",
  • "amount": -120.5,
  • "counterpartName": "Amazon EU",
  • "counterpartAccountNumber": "9876543210",
  • "counterpartIban": "DE44500105175407324931",
  • "purpose": "Office supplies purchase",
  • "counterpartCustomerReference": "reference"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Delete bank account transactions

Deletes a bank account transaction by id.

A transaction may only be deleted through the surface that manages its account's provider (public API for API accounts, partner API for PARTNER accounts). Requests targeting an account managed by another surface are rejected with 409 BANK_ACCOUNT_NOT_MODIFIABLE.

path Parameters
id
required
integer <int64>

The ID of the bank account transaction

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "id": 0
}

Cashflow

Get cashflow

Retrieves the cashflow of the authenticated company aggregated per period. Each period bucket contains the opening and closing balances (actual, prognosed, total and plan), the sales and purchases totals, the amounts per category, the aggregated income and expense details, and any non-financial KPIs. Per-period overdraft and liquidity figures are returned alongside, keyed by the same period start dates. All amounts are returned with two decimals. Only periods within the resolved from/to range are returned.

When scenarioId is omitted, the base forecast scenario is used. When from/to are omitted, the range defaults to 6 periods in the past and 18 periods in the future. The range between from and to must not exceed 36 periods.

query Parameters
scenarioId
integer <int64>
Example: scenarioId=1

ID of the scenario to calculate the cashflow for. Defaults to the base forecast scenario.

period
string (CashflowPeriod)
Default: "MONTH"
Enum: "MONTH" "WEEK" "DAY"

Aggregation period of the cashflow buckets.

from
string <date>
Example: from=2025-01-01

Start of the range in ISO 8601 format (yyyy-MM-dd). Must be the first day of the requested period (first day of the month for MONTH, Monday for WEEK). When omitted it defaults to 6 periods before to, or before the current date when to is omitted as well.

to
string <date>
Example: to=2025-12-31

End of the range in ISO 8601 format (yyyy-MM-dd). Must be the last day of the requested period (last day of the month for MONTH, Sunday for WEEK) and not before from. When omitted it defaults to 18 periods after from, or after the current date when from is omitted as well.

Responses

Response samples

Content type
application/json
{
  • "cashflow": {
    }
}