Documentation Powered by ReDoc

cashbuzz platform API (1.2.1)

Download OpenAPI specification:Download

Cashbuzz GmbH (finanzmining.de): service@finanzmining.de URL: https://finanzmining.de Terms of Service

About this document

This is the API documentation for the cashbuzz.io engine that provides financial data access & analytics as well as process bricks for sales & retention. The API includes
  • access to bank accounts (checking, savings, cards, etc.) and payment transactions via AISP
  • access to trades, securities and investment accounts via AISP
  • push of user, bank account and transaction data into analytics platform
  • transaction enrichment including classification with 500+ categories and identification of couterparties
  • detection of subscriptions and contracts together with subscription/contract details like contract and customer idents
  • detailed financial user profiles, e.g. user "P&L", liquidity analytics, etc.
  • detailed predictions of transactions, subscriptions/contracts, financial statements and other analytics
  • user attributes, life cycle events and other user data
  • user affinities to consumer categories ands signaling for cross-selling opportunities
  • user and application tracking and logging
  • setup, configuration and processing of retention & sales schemes
  • Cashback and voucher processing

Impressum/Legal Notice
Find the full API Documentation here

Authentication

cashbuzzKey

Security Scheme Type API Key
Header parameter name: x-api-Key

authKey

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "secure token"

Banks

Get and search all banks

Get and search banks from cashbuzzÔÇÖ database of banks. Must pass the authorized user's access token, or your client's access token. You can set optional search criteria to get only those banks that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
query Parameters
ids
Array of integers <int64>

A comma-separated list of bank identifiers. If specified, then only banks whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 1000.

search
string

If specified, then only those banks will be contained in the result whose 'name', 'blz', 'bic' or 'city' contains the given search string (the matching works case-insensitive). If no banks contain the search string in any of the regarded fields, then the result will be an empty list. Note that you may also pass an IBAN in this field, in which case cashbuzz will try to find the related bank in its database and regard only this bank for the search. Also note: If the given search string consists of several terms (separated by whitespace), then ALL of these terms must apply to a bank in order for it to get included into the result.

isSupported
boolean

If specified, then only supported (in case of 'true' value) or unsupported (in case of 'false' value) banks will be regarded.

pinsAreVolatile
boolean

If specified, then only those banks will be regarded that have the given value (true or false) for their 'pinsAreVolatile' field.

supportedDataSources
Array of strings

Comma-separated list of data sources. Possible values: WEB_SCRAPER,FINTS_SERVER. If this parameter is specified, then only those banks will be regarded in the search that support ALL of the given data sources. Note that this does NOT imply that those data sources must be the only data sources that are supported by a bank.

location
Array of strings

Comma-separated list of two-letter country codes (ISO 3166 ALPHA-2). If set, then only those banks will be regarded in the search that are located in the specified countries. Notes: Banks which do not have a location set (i.e. international institutes) will ALWAYS be regarded in the search, independent of what you specify for this field. When you pass a country code that doesn't exist in the ISO 3166 ALPHA-2 standard, then the service will respond with 400 BAD_REQUEST.

isTestBank
boolean

If specified, then only those banks will be regarded that have the given value (true or false) for their 'isTestBank' field.

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 500 ]
Default: 20

Maximum number of records per page. Can be at most 500. NOTE: Due to its validation and visualization, the swagger frontend might show very low performance, or even crashes, when a service responds with a lot of data. It is recommended to use a HTTP client like Postman or DHC instead of our swagger frontend for service calls with large page sizes.

order
Array of strings

Determines the order of the results. You can order the results by 'id', 'name', 'blz', 'bic' or 'popularity'. The default order for all services is 'id,asc'. You can also order by multiple properties. In that case the order of the parameters passed is important. Example: '/banks?order=name,desc&order=id,asc' will return banks ordered by 'name' (descending), where banks with the same 'name' are ordered by 'id' (ascending). The general format is: 'property[,asc|desc]', with 'asc' being the default value. Please note that ordering by multiple fields is not supported in our swagger frontend, but you can test this feature with any HTTP tool of your choice (e.g. postman or DHC).

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/banks?ids=SOME_ARRAY_VALUE&search=SOME_STRING_VALUE&isSupported=SOME_BOOLEAN_VALUE&pinsAreVolatile=SOME_BOOLEAN_VALUE&supportedDataSources=SOME_ARRAY_VALUE&location=SOME_ARRAY_VALUE&isTestBank=SOME_BOOLEAN_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&order=SOME_ARRAY_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "banks": [
    ],
  • "paging": {
    }
}

Get a bank

Get a single bank from cashbuzzÔÇÖ database of banks. You have to pass the bank's identifier, and either the authorized user's access token, or your client's access token.

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64> [\d]+

Identifier of requested bank

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/banks/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "loginHint": "string",
  • "bic": "string",
  • "blz": "string",
  • "blzs": [
    ],
  • "loginFieldUserId": "string",
  • "loginFieldCustomerId": "string",
  • "loginFieldPin": "string",
  • "isCustomerIdPassword": true,
  • "isSupported": true,
  • "supportedDataSources": [
    ],
  • "pinsAreVolatile": true,
  • "location": "string",
  • "city": "string",
  • "isTestBank": true,
  • "popularity": 0,
  • "health": 100,
  • "lastCommunicationAttempt": "string",
  • "lastSuccessfulCommunication": "string"
}

Bank Connections

Get all bank connections

Get bank connections of the user that is authorized by the access token. Must pass the user's access token. You can set optional search criteria to get only those bank connections that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
query Parameters
ids
Array of integers <int64>

A comma-separated list of bank connection identifiers. If specified, then only bank connections whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 1000.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/bankConnections?ids=SOME_ARRAY_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

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

Delete all bank connections

Delete all bank connections of the user that is authorized by the access token. Must pass the user's access token.
Note: If at least one bank connection is busy (currently in the process of import, update, or transactions categorization), then this service will perform no action at all.

Authorizations:
cashbuzzKeyauthKey

Responses

Request samples 

curl --request DELETE \
  --url https://api.cashbuzz.io/v01/bankConnections \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

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

Import a new bank connection

Imports a new bank connection for a specific user. Must pass the API-key and the user's access token. All bank accounts will be downloaded and imported with their current balances, transactions and supported two-step-procedures (note that the amount of available transactions may vary between banks, e.g. some banks deliver all transactions from the past year, others only deliver the transactions from the past three months). The balance and transactions download process runs asynchronously, so this service may return before all balances and transactions have been imported. Also, all downloaded transactions will be categorized by a separate background process that runs asynchronously too. To check the status of the balance and transactions download process as well as the background categorization process, see the status flags that are returned by the GET /bankConnections/ service.

The response contains an URL, that has to be opened in a Browser, so that the user can authenticate there with his bank. Until he has finished that you can get the status via the bankConnections-get all.

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json

Import bank connection parameters

bankId
required
integer <int64>

Bank Identifier

bankingUserId
string

Online banking user ID credential. Max length: 64. NOTES:
- if you import the 'demo connection', this field can be left unset;
- if the user will need to enter his credentials in cashbuzzÔÇÖÔÇÖ web form, this field can contain any value. It will be ignored.

bankingCustomerId
string

Online banking customer ID credential (for most banks this field can remain unset). Max length: 64. NOTES:
- if the user will need to enter his credentials in cashbuzzÔÇÖÔÇÖ web form, this field can contain any value. It will be ignored.

bankingPin
string

Online banking PIN. Max length: 170. Any symbols are allowed. NOTES:
- if you import the 'demo connection', this field can be left unset;
- if the user will need to enter his credentials in cashbuzzÔÇÖÔÇÖ web form, this field can be left unset or contain any value. It will be ignored.

storePin
boolean
Default: false

Whether to store the PIN. If the PIN is stored, it is not required to pass the PIN again when updating this bank connection or when executing orders (like money transfers). Default is false.

NOTES:
- before you set this field to true, please regard the 'pinsAreVolatile' flag of this connection's bank;
- this field is ignored in case when the user will need to use cashbuzzÔÇÖ web form. The user will be able to decide whether to store the PIN or not in the web form, depending on the 'pinStorageAvailableInWebForm' setting (see Client Configuration).

name
string

Custom name for the bank connection. Maximum length is 64. If you do not want to set a name, you can leave this field unset.

skipPositionsDownload
boolean
Default: false

Whether to skip the download of transactions and securities or not. If set to true, then cashbuzz will download just the accounts list with the accounts' information (like account name, number, holder, etc.), as well as the accounts' balances (if possible), but skip the download of transactions and securities. Default is false.

NOTES:
• If you skip the download of transactions and securities during an import or update, you can still download them on a later update (though you might not get all positions at a later point, because the date range in which the bank servers provide this data is usually limited). However, once cashbuzz has downloaded the transactions or securities for the first time, you will not be able to go back to skipping the download of transactions and securities! In other words: Once you make your first request with skipPositionsDownload=false for a certain bank connection, you will no longer be able to make a request with skipPositionsDownload=true for that same bank connection.
• If this bank connection is updated via cashbuzzÔÇÖÔÇÖ automatic batch update, then transactions and security positions will be downloaded in any case!
• For security accounts, skipping the downloading of the securities might result in the account's balance also not being downloaded.
• For Bausparen accounts, this field is ignored. cashbuzz will always download transactions for Bausparen accounts.

loadOwnerData
boolean
Default: false

Whether to load information about the bank connection owner(s) - see field 'owners'. Default value is 'false'.

maxDaysForDownload
integer <int32>
Default: 0

Use this parameter if you want to limit the date range for transactions download. The value depicts the number of days that cashbuzz will download transactions for, starting from - and including - today. For example, if you want to download only transactions from within the past 30 days (including today), then pass the value 30. The minimum allowed value is 14, the maximum value is 3650. You may also pass the value 0 though (which is also the default value when you do not specify this parameter), in which case there will be no limit to the transactions download and cashbuzz will try to get all transactions that it can. Please note that when you specify the parameter there is no guarantee that cashbuzz will actually download transactions for the entire given date range, as the bank servers may limit the date range on their own. Also note that this parameter only applies to transactions, not to security positions; cashbuzz will always download all positions that it can get.

This flag is currently not guaranteed to work for all banks!

accountTypeIds
Array of integers <int64>

Whitelist of identifiers of cashbuzz account types that are considered for the import. Only accounts whose type matches with one of the given types will be imported. Note that when the bank connection does not contain any accounts of the given types, the import will fail with error code NO_ACCOUNTS_FOR_TYPE_LIST. If no whitelist is given, then all accounts will be imported.


1 = Checking,
2 = Savings,
3 = CreditCard,
4 = Security,
5 = Loan,
6 = Pocket (DEPRECATED; will not be returned for any account unless this type has explicitly been set via PATCH),
7 = Membership,
8 = Bausparen

This flag is currently not guaranteed to work for all banks!

challengeResponse
string

Challenge response. This field should be set only when the previous attempt of importing the bank connection failed with HTTP code 510, i.e. the bank sent a challenge for the user for an additional authentication. In this case, this field must contain the response to the bank's challenge. Note that in the context of cashbuzzÔÇÖ web form flow, cashbuzz will automatically deal with getting the challenge response from the user via the web form.

Responses

Request samples

Content type
application/json
{
  • "bankId": 0,
  • "bankingUserId": "string",
  • "bankingCustomerId": "string",
  • "bankingPin": "string",
  • "storePin": false,
  • "name": "string",
  • "skipPositionsDownload": false,
  • "loadOwnerData": false,
  • "maxDaysForDownload": 0,
  • "accountTypeIds": [
    ],
  • "challengeResponse": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "bankId": 0,
  • "bank": {
    },
  • "name": "string",
  • "bankingUserId": "string",
  • "bankingCustomerId": "string",
  • "bankingPin": "string",
  • "type": "ONLINE",
  • "updateStatus": "IN_PROGRESS",
  • "lastManualUpdate": {
    },
  • "lastAutoUpdate": {
    },
  • "twoStepProcedures": [
    ],
  • "ibanOnlyMoneyTransferSupported": true,
  • "ibanOnlyDirectDebitSupported": true,
  • "collectiveMoneyTransferSupported": true,
  • "defaultTwoStepProcedureId": "string",
  • "accountIds": [
    ],
  • "owners": [
    ]
}

Get a web form Status

Get a web form of the user that is authorized by the access token. Must pass the web form's identifier and the user's access token. Note that every web form resource is automatically removed from the cashbuzz/finapi system 24 hours after its creation.

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64> [\d]+

Identifier of web form

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/bankConnections/import/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": 0,
  • "token": "string",
  • "status": "NOT_YET_OPENED",
  • "serviceResponseCode": 0,
  • "serviceResponseBody": "string"
}

Import a bank connection

Imports and groups all the bank data the end user has at the specific bank into a bank connection (identifiable with a bankConnectionId). The endpoint connects to all available interfaces(XS2A, finTS and Web Scraper) for the bank. Hence, the end user will be prompted for credentials and SCA for every loop over each of the interface. For best results, consider your use case and review the API parameter, accountTypes list before you begin your integration.

All bank accounts will be downloaded and imported with their current balances, transactions and supported two-step-procedures (note that the amount of available transactions may vary between banks, e.g. some banks deliver all transactions from the past year, others only deliver the transactions from the past three months). The balance and transactions download process runs asynchronously, so this service may return before all balances and transactions have been imported. Also, all downloaded transactions will be categorized by a separate background process that runs asynchronously too. To check the status of the balance and transactions download process as well as the background categorization process, see the status flags that are returned by the GET /bankConnections/ service. For a more in-depth understanding of the import process, please also read this page on our documentation: Post Processing of Bank Account Import/Update.

In order to test the API, you can import a "demo connection". To import the demo connection, you need to pass the identifier of the "finAPI Test Bank". For more details, please see the associated documentation.

In case the API request is syntactically correct, the service will respond with HTTP return code 201 and a unique URL. You must direct your user to our web form with the URL.

Must pass the user's access token.

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json
object or null (ImportBankDetails)

Bank details. When not provided at the API-level, the end-user can search for the bank on the Web Form directly and then proceed with the import.

bankConnectionName
string or null [ 1 .. 64 ] characters

Custom name for the bank connection

skipPositionsDownload
boolean or null
Default: false

Whether to skip the download of transactions and securities or not.
This parameter refers to the same parameter of the "Import a new bank connection" service in the finAPI Access API.

loadOwnerData
boolean or null
Default: false

Whether to load information about the bank connection owner(s).
This parameter refers to the same parameter of the "Import a new bank connection" service in the finAPI Access API.

maxDaysForDownload
integer or null <int32> <= 3650
Default: 0

Defines the limit of how many days of the transaction history will be requested from the bank.
This parameter refers to the same parameter of the "Import a new bank connection" service in the finAPI Access API.

accountTypes
Array of strings or null (AccountType) unique
Enum: "BAUSPAREN" "CHECKING" "CREDIT_CARD" "LOAN" "MEMBERSHIP" "SAVINGS" "SECURITY"

A set of account types that are considered for the import. If no values is given, then all accounts will be imported.
This parameter refers to the same parameter of the "Import a new bank connection" service in the finAPI Access API.

object or null (Callbacks)

Callbacks for the instantiated web form. Find more info in the Web Form 2.0 Public Documentation.

profileId
string or null 36 characters

The profile to be applied to the web form.
This will overwrite the default profile, if such a profile exists.

redirectUrl
string or null [ 1 .. 2048 ] characters https://(www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\...

The URL where the end-user will be redirected to after completing the bank login and (possibly) the SCA on the bank's website. Must always be provided by mandators with FULLY_LICENSED or AISP license type, and may not be provided by mandators with other license types. Find more info in the Web Form 2.0 Public Documentation.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "bank": {
    },
  • "bankConnectionName": "My bank connection",
  • "skipPositionsDownload": false,
  • "loadOwnerData": false,
  • "maxDaysForDownload": 0,
  • "accountTypes": [
    ],
  • "callbacks": {},
  • "profileId": "a2c9fc3b-1777-403c-8b2f-1ce4d90157a2",
  • "redirectUrl": "https://finapi.io/callback"
}

Response samples

Content type
application/json
{
  • "id": "946db09e-5bfc-11eb-ae93-0242ac130002",
  • "url": "https://webform.finapi.io/wf/946db09e-5bfc-11eb-ae93-0242ac130002",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "type": "STANDALONE_PAYMENT",
  • "status": "COMPLETED",
  • "payload": {
    }
}

Callback payload samples

Callback
POST: postOnBankConnectionImportFinalisedCallback
Content type
application/json
{
  • "webFormId": "31c508d8-51da-11eb-ae93-0242ac130002",
  • "status": "COMPLETED"
}

Update a bank connection

Update an existing bank connection of the user that is authorized by the access token. Downloads and imports the current account balances and new transactions. Must pass the connection's identifier and the user's access token. For more information about the processes of authentication, data download and transactions categorization, see POST /bankConnections/import. Note that supported two-step-procedures are updated as well. It may unset the current default two-step-procedure of the given bank connection (but only if this procedure is not supported anymore by the bank). You can also update the "demo connection" (in this case, the fields 'bankingPin', 'importNewAccounts', and 'skipPositionsDownload' will be ignored).

Note that you cannot trigger an update of a bank connection as long as there is still a previously triggered update running.

For a more in-depth understanding of the update process, please also read this article on our Dev Portal: Import & Update of Bank Connections / Accounts

NOTE: Depending on your license, this service may respond with HTTP code 251, containing an error message with an identifier of web form in it. In addition to that the response will also have included a 'Location' header, which contains the URL to the web form. In this case, you must forward your user to cashbuzz' web form. For a detailed explanation of the Web Form Flow, please refer to this article: finapi's Web Form Flow

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json

Update bank connection parameters

bankConnectionId
required
integer <int64>

Bank connection identifier

interface
string
Enum: "FINTS_SERVER" "WEB_SCRAPER" "XS2A"

The interface to use for connecting with the bank, default is currently FINTS_SERVER.

importNewAccounts
boolean

Whether new accounts that have not yet been imported will be imported or not. Default is false.

NOTES:
• For best performance of the bank connection update, you should not enable this flag unless you really expect new accounts to be available in the connection. It is recommended to let your users tell you through your application when they want the service to look for new accounts.
• If you have imported a bank connection using specific accountTypeIds (e.g. 1,2 to import checking and saving accounts), you would import all other accounts (e.g. security accounts or credit cards) by setting importNewAccounts to true. To avoid importing account types that you are not interested in, make sure this field is undefined or set to false.

Array of objects (AccountReference)

List of accounts for which access is requested from the bank. It may only be passed if the bank interface has the DETAILED_CONSENT property set. if omitted, finAPI will use the list of existing accounts. Note that the parameter is still required if you want to import new accounts (i.e. call with importNewAccounts=true).

loadOwnerData
boolean
Default: false

Whether to load/refresh information about the bank connection owner(s) - see field 'owners'. Default value is 'false'. Note that owner data is NOT loaded/refreshed during finAPI's automatic bank connection update.

Responses

Request samples

Content type
application/json
{
  • "bankConnectionId": 1,
  • "interface": "XS2A",
  • "importNewAccounts": true,
  • "accountReferences": [
    ],
  • "loadOwnerData": false
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "bankId": 0,
  • "bank": {
    },
  • "name": "string",
  • "bankingUserId": "string",
  • "bankingCustomerId": "string",
  • "bankingPin": "string",
  • "type": "ONLINE",
  • "updateStatus": "IN_PROGRESS",
  • "lastManualUpdate": {
    },
  • "lastAutoUpdate": {
    },
  • "twoStepProcedures": [
    ],
  • "ibanOnlyMoneyTransferSupported": true,
  • "ibanOnlyDirectDebitSupported": true,
  • "collectiveMoneyTransferSupported": true,
  • "defaultTwoStepProcedureId": "string",
  • "accountIds": [
    ],
  • "owners": [
    ]
}

Get a bank connection

Get a single bank connection of the user that is authorized by the access token. Must pass the connection's identifier and the user's access token.

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64> [\d]+

Identifier of requested bank connection

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/bankConnections/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": 0,
  • "bankId": 0,
  • "bank": {
    },
  • "name": "string",
  • "bankingUserId": "string",
  • "bankingCustomerId": "string",
  • "bankingPin": "string",
  • "type": "ONLINE",
  • "updateStatus": "IN_PROGRESS",
  • "lastManualUpdate": {
    },
  • "lastAutoUpdate": {
    },
  • "twoStepProcedures": [
    ],
  • "ibanOnlyMoneyTransferSupported": true,
  • "ibanOnlyDirectDebitSupported": true,
  • "collectiveMoneyTransferSupported": true,
  • "defaultTwoStepProcedureId": "string",
  • "accountIds": [
    ],
  • "owners": [
    ]
}

Delete a bank connection

Delete a single bank connection of the user that is authorized by the access token, including all of its accounts and their transactions and balance data. Must pass the bank connection's identifier and the user's access token.
Note: A bank connection cannot get deleted while it is in the process of import, update, or transactions categorization.

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64> [\d]+

Identifier of the bank connection to delete

Responses

Request samples 

curl --request DELETE \
  --url https://api.cashbuzz.io/v01/bankConnections/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_description": "string"
}

Edit a bank connection

Change the stored authentication credentials (banking user ID, banking customer ID, and banking PIN), or other fields of the bank connection. Must pass the connection's identifier and the user's access token.

Note that a bank connection's credentials cannot be changed while it is in the process of import, update, or transactions categorization.

NOTE: Depending on your license, this service may respond with HTTP code 251, containing an error message with an identifier of web form in it. In addition to that the response will also have included a 'Location' header, which contains the URL to the web form. In this case, you must forward your user to cashbuzz' web form. For a detailed explanation of the Web Form Flow, please refer to this article: finapis's Web Form Flow

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64> [\d]+

Identifier of the bank connection to change the parameters for

Request Body schema: application/json

New bank connection parameters

bankingUserId
string

New online banking user ID. If you do not want to change the current user ID let this field remain unset. In case you need to use cashbuzz web form to let the user update the field, just set the field to any value, so that the service recognizes that you wish to use the web form flow. Note that you cannot clear the current user ID, i.e. a bank connection must always have a user ID (except for when it is a 'demo connection'). Max length: 64.

bankingCustomerId
string

New online banking customer ID. If you do not want to change the current customer ID let this field remain unset. In case you need to use cashbuzzÔÇÖÔÇÖ web form to let the user update the field, just set the field to non-empty value, so that the service recognizes that you wish to use the web form flow. If you want to clear the current customer ID, set the field's value to an empty string (""). Max length: 64.

bankingPin
string

New online banking PIN. If you do not want to change the current PIN let this field remain unset. In case you need to use cashbuzz web form to let the user update the field, just set the field to non-empty value, so that the service recognizes that you wish to use the web form flow. If you want to clear the current PIN, set the field's value to an empty string ("").

NOTE: Before you set this field, please regard the 'pinsAreVolatile' flag of this connection's bank.
Any symbols are allowed. Max length: 170.

defaultTwoStepProcedureId
string

New default two-step-procedure. Must match the 'procedureId' of one of the procedures that are listed in the bank connection. If you do not want to change this field let it remain unset. If you want to clear the current default two-step-procedure, set the field's value to an empty string ("").

name
string

New name for the bank connection. Maximum length is 64. If you do not want to change the current name let this field remain unset. If you want to clear the current name, set the field's value to an empty string ("").

Responses

Request samples

Content type
application/json
{
  • "bankingUserId": "string",
  • "bankingCustomerId": "string",
  • "bankingPin": "string",
  • "defaultTwoStepProcedureId": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "bankId": 0,
  • "bank": {
    },
  • "name": "string",
  • "bankingUserId": "string",
  • "bankingCustomerId": "string",
  • "bankingPin": "string",
  • "type": "ONLINE",
  • "updateStatus": "IN_PROGRESS",
  • "lastManualUpdate": {
    },
  • "lastAutoUpdate": {
    },
  • "twoStepProcedures": [
    ],
  • "ibanOnlyMoneyTransferSupported": true,
  • "ibanOnlyDirectDebitSupported": true,
  • "collectiveMoneyTransferSupported": true,
  • "defaultTwoStepProcedureId": "string",
  • "accountIds": [
    ],
  • "owners": [
    ]
}

Accounts

Get and search all accounts

Get bank accounts of the user that is authorized by the access token. Must pass the user's access token. You can set optional search criteria to get only those bank accounts that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
query Parameters
ids
Array of integers <int64>

A comma-separated list of account identifiers. If specified, then only accounts whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 1000.

search
string

If specified, then only those accounts will be contained in the result whose 'accountName', 'iban', 'accountNumber' or 'subAccountNumber' contains the given search string (the matching works case-insensitive). If no accounts contain the search string in any of these fields, then the result will be an empty list. NOTE: If the given search string consists of several terms (separated by whitespace), then ALL of these terms must be contained in the searched fields in order for an account to get included into the result.

accountTypeIds
Array of integers <int64>

A comma-separated list of account types. If specified, then only accounts that relate to the given types will be regarded. If not specified, then all accounts will be regarded.

bankConnectionIds
Array of integers <int64>

A comma-separated list of bank connection identifiers. If specified, then only accounts that relate to the given bank connections will be regarded. If not specified, then all accounts will be regarded.

minLastSuccessfulUpdate
string

Lower bound for an account's last successful update date, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only accounts whose 'lastSuccessfulUpdate' is equal to or later than the given date will be regarded.

maxLastSuccessfulUpdate
string

Upper bound for an account's last successful update date, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only accounts whose 'lastSuccessfulUpdate' is equal to or earlier than the given date will be regarded.

minBalance
number

If specified, then only accounts whose balance is equal to or greater than the given balance will be regarded. Can contain a positive or negative number with at most two decimal places. Examples: -300.12, or 90.95

maxBalance
number

If specified, then only accounts whose balance is equal to or less than the given balance will be regarded. Can contain a positive or negative number with at most two decimal places. Examples: -300.12, or 90.95

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/accounts?ids=SOME_ARRAY_VALUE&search=SOME_STRING_VALUE&accountTypeIds=SOME_ARRAY_VALUE&bankConnectionIds=SOME_ARRAY_VALUE&minLastSuccessfulUpdate=SOME_STRING_VALUE&maxLastSuccessfulUpdate=SOME_STRING_VALUE&minBalance=SOME_NUMBER_VALUE&maxBalance=SOME_NUMBER_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

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

Upload accounts

Upload a list of accounts to later upload transactions to these accounts.
Notes:
- You might want to specify the lastSuccessfulUpdate to set the accounts closingbalance to a specific date, if not specified cashbuzz assumes today
- If no accountCurrency is specified it defaults to EUR

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json

List of accounts

required
Array of objects (Account)

Array of accounts

Responses

Request samples

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

Response samples

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

Delete all accounts

Delete all accounts of the user that is authorized by the access token, including all transactions and balance data. Must pass the user's access token.

Notes:
- Deleting all of the user's accounts also deletes all of his bank connections, if existing.
- If at least one of the user's bank connections in currently in the process of import, update, or transactions categorization, then this service might perform no action at all.

Authorizations:
cashbuzzKeyauthKey

Responses

Request samples 

curl --request DELETE \
  --url https://api.cashbuzz.io/v01/accounts \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

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

Get an account

Get a single bank account of the user that is authorized by the access token. Must pass the account's identifier and the user's access token.

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
string <uuid>

Identifier of requested account

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/accounts/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": 1,
  • "bankConnectionId": 1,
  • "accountName": "Testaccount",
  • "iban": "DE89370400440532013000",
  • "accountNumber": "12345678",
  • "subAccountNumber": "1234",
  • "accountHolderName": "Jhon Doe",
  • "accountHolderId": "XXXXX",
  • "accountCurrency": "EUR",
  • "accountType": "Checking",
  • "balance": 99.99,
  • "overdraft": 99.99,
  • "overdraftLimit": 99.99,
  • "availableFunds": 99.99,
  • "isNew": true,
  • "interfaces": [
    ],
  • "isSeized": false,
  • "categorization_status": 0,
  • "cb_id": "5c5da2cd-60d0-4080-a41f-90af65b0a3dc",
  • "account_qme": "string"
}

Delete an account

Delete a single bank account of the user that is authorized by the access token, including its transactions and balance data. Must pass the account's identifier and the user's access token.

Notes:
- You cannot delete an account while the bank connection that it relates to is currently in the process of import, update, or transactions categorization.
- When the last remaining account of a bank connection gets deleted, then the bank connection itself will get deleted as well!

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
string <uuid>

Identifier of requested account

Responses

Request samples 

curl --request DELETE \
  --url https://api.cashbuzz.io/v01/accounts/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_description": "string"
}

Edit an account

Change the name and/or the type and/or the 'isNew' flag and/or payout account-flag of a single bank account of the user that is authorized by the access token. Must pass the account's identifier, the account's new name and/or type and/or 'isNew' flag, and the user's access token. Note that the first account automatically gets the payout-flag and that only one account can be a payout account.

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
string <uuid>

Identifier of requested account

Request Body schema: application/json

New account name and/or type and/or 'isNew' flag and/or payout account-flag

id
required
integer <int64>

Account identifier

bankConnectionId
integer or null <int64>

Identifier of the bank connection that this account belongs to, if it was importet directly it's 0 or None.

accountName
string or null

Account name

iban
string or null

Account's IBAN. Note that this field can change from 'null' to a value - or vice versa - any time when the account is being updated. This is subject to changes within the bank's internal account management.

accountNumber
string or null

(National) account number. Note that this value might change whenever the account is updated (for example, leading zeros might be added or removed).

subAccountNumber
string or null

Account's sub-account-number. Note that this field can change from 'null' to a value - or vice versa - any time when the account is being updated. This is subject to changes within the bank's internal account management.

accountHolderName
string or null

Name of the account holder

accountHolderId
string or null

Bank's internal identification of the account holder. Note that if your client has no license for processing this field, it will always be 'XXXXX'

accountCurrency
string or null

Account's currency

accountType
string or null
Enum: "Checking" "Savings" "CreditCard" "Security" "Loan" "Pocket" "Membership" "Bausparen"

An account type.

Checking,
Savings,
CreditCard,
Security,
Loan,
Pocket (DEPRECATED; will not be returned for any account unless this type has explicitly been set via PATCH),
Membership,
Bausparen

balance
number or null

Current account balance

overdraft
number or null

Current overdraft

overdraftLimit
number or null

Overdraft limit

availableFunds
number or null

Current available funds. Note that this field is only set if finAPI can make a definite statement about the current available funds. This might not always be the case, for example if there is not enough information available about the overdraft limit and current overdraft.

isNew
boolean or null

Indicating whether this account is 'new' or not. Any newly imported account will have this flag initially set to true, and remain so until you set it to false (see PATCH /accounts/). How you use this field is up to your interpretation, however it is recommended to set the flag to false for all accounts right after the initial import of the bank connection. This way, you will be able recognize accounts that get newly imported during a later update of the bank connection, by checking for any accounts with the flag set to true right after an update.

Array of objects or null (AccountInterface)

Set of interfaces to which this account is connected

isSeized
boolean or null

Whether this account is seized. Note that this information is not received from the bank, but determined by finAPI based on the available account information.

categorization_status
integer or null <int32>

Current status of the categorization and subscribing
0: All transactiondata of this account are up-to-date
1: Analyzing subscriptions
2: Categorization in process
3: Data synchronization in process

cb_id
string or null <uuid>

internal identification of the transaction

account_qme
string or null

The categorization of the accountholder. Setting it up improves the categorization of the transactions. The possible values can be found in /descriptions/classes

Responses

Request samples

Content type
application/json
{
  • "id": 1,
  • "bankConnectionId": 1,
  • "accountName": "Testaccount",
  • "iban": "DE89370400440532013000",
  • "accountNumber": "12345678",
  • "subAccountNumber": "1234",
  • "accountHolderName": "Jhon Doe",
  • "accountHolderId": "XXXXX",
  • "accountCurrency": "EUR",
  • "accountType": "Checking",
  • "balance": 99.99,
  • "overdraft": 99.99,
  • "overdraftLimit": 99.99,
  • "availableFunds": 99.99,
  • "isNew": true,
  • "interfaces": [
    ],
  • "isSeized": false,
  • "categorization_status": 0,
  • "cb_id": "5c5da2cd-60d0-4080-a41f-90af65b0a3dc",
  • "account_qme": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "bankConnectionId": 1,
  • "accountName": "Testaccount",
  • "iban": "DE89370400440532013000",
  • "accountNumber": "12345678",
  • "subAccountNumber": "1234",
  • "accountHolderName": "Jhon Doe",
  • "accountHolderId": "XXXXX",
  • "accountCurrency": "EUR",
  • "accountType": "Checking",
  • "balance": 99.99,
  • "overdraft": 99.99,
  • "overdraftLimit": 99.99,
  • "availableFunds": 99.99,
  • "isNew": true,
  • "interfaces": [
    ],
  • "isSeized": false,
  • "categorization_status": 0,
  • "cb_id": "5c5da2cd-60d0-4080-a41f-90af65b0a3dc",
  • "account_qme": "string"
}

Transactions

Get and search all transactions

Get transactions of the user that is authorized by the access token. Must pass the user's access token. You can set optional search criteria to get only those transactions that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service for the last 31 days.

Authorizations:
cashbuzzKeyauthKey
query Parameters
ids
Array of integers <int64>

A comma-separated list of transaction identifiers. If specified, then only transactions whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 1000.

view
string
Enum: "bankView" "userView"

This parameter defines cashbuzzÔÇÖÔÇÖ logical view on the transactions when querying them: 'bankView' regards only the original transactions as they were received from the bank, without considering how the transactions might have gotten split by the user (see POST /transactions//split). This means that if a transaction is split into logical sub-transactions, then the service will still regard only the original transaction, and NOT the logical sub-transactions in its processing (though for convenience, the transactions will have the data of their sub-transactions included in the response). 'userView' by contrast regards the transactions as they exist for the user. For transactions that have not been split into logical sub-transactions, there is no difference to the "bankView". But for transaction that have been split into logical sub-transactions, the service will ONLY regard these sub-transactions, and not the originally received transaction (though for convenience, the sub-transactions will have the identifier of their original transaction included in the response).

search
string

If specified, then only those transactions will be contained in the result whose 'purpose' or counterpart fields contain the given search string (the matching works case-insensitive). If no transactions contain the search string in any of these fields, then the result will be an empty list. NOTE: If the given search string consists of several terms (separated by whitespace), then ALL of these terms must be contained in the searched fields in order for a transaction to get included into the result.

counterpart
string

If specified, then only those transactions will be contained in the result whose counterpart fields contain the given search string (the matching works case-insensitive). If no transactions contain the search string in any of the counterpart fields, then the result will be an empty list. NOTE: If the given search string consists of several terms (separated by whitespace), then ALL of these terms must be contained in the searched fields in order for a transaction to get included into the result.

purpose
string

If specified, then only those transactions will be contained in the result whose purpose field contains the given search string (the matching works case-insensitive). If no transactions contain the search string in the purpose field, then the result will be an empty list. NOTE: If the given search string consists of several terms (separated by whitespace), then ALL of these terms must be contained in the purpose in order for a transaction to get included into the result.

accountIds
Array of integers <int64>

A comma-separated list of account identifiers. If specified, then only transactions that relate to the given accounts will be regarded. If not specified, then all accounts will be regarded.

minBankBookingDate
string

Lower bound for a transaction's booking date as returned by the bank (= original booking date), in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only transactions whose 'bankBookingDate' is equal to or later than the given date will be regarded.

maxBankBookingDate
string

Upper bound for a transaction's booking date as returned by the bank (= original booking date), in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only transactions whose 'bankBookingDate' is equal to or earlier than the given date will be regarded. !IMPORTANT! If the given date is in the future, cashbuzz will try to predict upcoming transactions.

minValueDate
string

Lower bound for a transaction's value date as returned by the bank, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only transactions whose 'valueDate' is equal to or later than the given date will be regarded.

maxValueDate
string

Upper bound for a transaction's value date as returned by the bank, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only transactions whose 'valueDate' is equal to or earlier than the given date will be regarded. !IMPORTANT! If the given date is in the future, cashbuzz will try to predict upcoming transactions.

only_predicted
boolean
Default: false

If set to 'true' only predicted transactions are getting returned. If no maxDate is set, the maxBankBookingDate is set to 90 days from today.

minAmount
number

If specified, then only transactions whose amount is equal to or greater than the given amount will be regarded. Can contain a positive or negative number with at most two decimal places. Examples: -300.12, or 90.95

maxAmount
number

If specified, then only transactions whose amount is equal to or less than the given amount will be regarded. Can contain a positive or negative number with at most two decimal places. Examples: -300.12, or 90.95

qme
string

If specified, then only those transactions will be contained in the result whose qme matches the requested. By setting include_sub_qme to true you can include all the children of the specified group

include_sub_qme
boolean
Default: false

This flag controls how the given 'qme' is handled. If set to 'true', then all transactions of a given qme, as well as all transactions of any of its sub-qme will be regarded. If set to 'false', then sub-categories of a given qme will not be regarded and only those transactions are regarded whose qme matches the specified qme. The default value for this flag is 'false'.

qorg
string

If specified, then only those transactions will be contained in the result whose qorg matches the requested. By setting include_sub_qorg to true you can include all the children of the specified group

include_sub_qorg
boolean
Default: false

This flag controls how the given 'qorg' is handled. If set to 'true', then all transactions of a given qorg, as well as all transactions of any of its sub-qorg will be regarded. If set to 'false', then sub-categories of a given qorg will not be regarded and only those transactions are regarded whose qorg matches the specified qorg. The default value for this flag is 'false'.

qsubject
string

If specified, then only those transactions will be contained in the result whose qsubject matches the requested. By setting include_sub_qsubject to true you can include all the children of the specified group

include_sub_qsubject
boolean
Default: false

This flag controls how the given 'qsubject' is handled. If set to 'true', then all transactions of a given qsubject, as well as all transactions of any of its sub-qsubject will be regarded. If set to 'false', then sub-categories of a given qsubject will not be regarded and only those transactions are regarded whose qsubject matches the specified qsubject. The default value for this flag is 'false'.

qaction
string

If specified, then only those transactions will be contained in the result whose qaction matches the requested. By setting include_sub_qaction to true you can include all the children of the specified group

include_sub_qaction
boolean
Default: false

This flag controls how the given 'qaction' is handled. If set to 'true', then all transactions of a given qaction, as well as all transactions of any of its sub-qaction will be regarded. If set to 'false', then sub-categories of a given qaction will not be regarded and only those transactions are regarded whose qaction matches the specified qaction. The default value for this flag is 'false'.

group_gstd
string

If specified, then only those transactions will be contained in the result whose group_gstd matches the requested. By setting include_sub_gstd to true you can include all the children of the specified group

include_sub_gstd
boolean
Default: false

This flag controls how the given 'group_gstd' is handled. If set to 'true', then all transactions of a given group_gstd, as well as all transactions of any of its sub-group_gstd will be regarded. If set to 'false', then sub-categories of a given group_gstd will not be regarded and only those transactions are regarded whose group_gstd matches the specified group_gstd. The default value for this flag is 'false'.

group_gcix
string

If specified, then only those transactions will be contained in the result whose group_gcix matches the requested. By setting include_sub_gcix to true you can include all the children of the specified group

include_sub_gcix
boolean
Default: false

This flag controls how the given 'group_gcix' is handled. If set to 'true', then all transactions of a given group_gcix, as well as all transactions of any of its sub-group_gcix will be regarded. If set to 'false', then sub-categories of a given group_gcix will not be regarded and only those transactions are regarded whose group_gcix matches the specified group_gcix. The default value for this flag is 'false'.

group_gbix
string

If specified, then only those transactions will be contained in the result whose group_gbix matches the requested. By setting include_sub_gbix to true you can include all the children of the specified group

include_sub_gbix
boolean
Default: false

This flag controls how the given 'group_gstd' is handled. If set to 'true', then all transactions of a given group_gbix, as well as all transactions of any of its sub-group_gbix will be regarded. If set to 'false', then sub-categories of a given group_gbix will not be regarded and only those transactions are regarded whose group_gbix matches the specified group_gbix. The default value for this flag is 'false'.

group_gcon
string

If specified, then only those transactions will be contained in the result whose group_gcon matches the requested. By setting include_sub_gcon to true you can include all the children of the specified group

include_sub_gcon
boolean
Default: false

This flag controls how the given 'group_gcon' is handled. If set to 'true', then all transactions of a given group_gcon, as well as all transactions of any of its sub-group_gcon will be regarded. If set to 'false', then sub-categories of a given group_gcon will not be regarded and only those transactions are regarded whose group_gcon matches the specified group_gcon. The default value for this flag is 'false'.

minImportDate
string

Lower bound for a transaction's import date, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only transactions whose 'importDate' is equal to or later than the given date will be regarded.

maxImportDate
string

Upper bound for a transaction's import date, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only transactions whose 'importDate' is equal to or earlier than the given date will be regarded.

order
Array of strings

Determines the order of the results. You can use the following fields for ordering the response: 'id', 'parentId', 'accountId', 'valueDate', 'bankBookingDate', 'cashbuzzBookingDate', 'amount', 'purpose', 'counterpartName', 'counterpartAccountNumber', 'counterpartIban', 'counterpartBlz', 'counterpartBic', 'type', 'primanota', 'category.id', 'category.name', 'isPotentialDuplicate', 'isNew' and 'importDate'. The default order for all services is 'id,asc'. You can also order by multiple properties. In that case the order of the parameters passed is important. Example: '/transactions?order=cashbuzzBookingDate,desc&order=counterpartName' will return the latest transactions first. If there are more transactions on the same day, then these transactions are ordered by the counterpart name (ascending). The general format is: 'property[,asc|desc]', with 'asc' being the default value. Please note that ordering by multiple fields is not supported in our swagger frontend, but you can test this feature with any HTTP tool of your choice (e.g. postman or DHC).

includeQClasses
boolean

If your license allows it, you can set it to true to retrieve the full set of categorization options. Activating it may increase the reported costs (depending on licence). Default is false.

includeRegiox
boolean

If your license allows it, you can set it to true to retrieve the full the regionality-value of a transaction. Default is false

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 500 ]
Default: 20

Maximum number of records per page. Can be at most 500. NOTE: Due to its validation and visualization, the swagger frontend might show very low performance, or even crashes, when a service responds with a lot of data. It is recommended to use a HTTP client like Postman or DHC instead of our swagger frontend for service calls with large page sizes.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/transactions?ids=SOME_ARRAY_VALUE&view=SOME_STRING_VALUE&search=SOME_STRING_VALUE&counterpart=SOME_STRING_VALUE&purpose=SOME_STRING_VALUE&accountIds=SOME_ARRAY_VALUE&minBankBookingDate=SOME_STRING_VALUE&maxBankBookingDate=SOME_STRING_VALUE&minValueDate=SOME_STRING_VALUE&maxValueDate=SOME_STRING_VALUE&only_predicted=SOME_BOOLEAN_VALUE&minAmount=SOME_NUMBER_VALUE&maxAmount=SOME_NUMBER_VALUE&qme=SOME_STRING_VALUE&include_sub_qme=SOME_BOOLEAN_VALUE&qorg=SOME_STRING_VALUE&include_sub_qorg=SOME_BOOLEAN_VALUE&qsubject=SOME_STRING_VALUE&include_sub_qsubject=SOME_BOOLEAN_VALUE&qaction=SOME_STRING_VALUE&include_sub_qaction=SOME_BOOLEAN_VALUE&group_gstd=SOME_STRING_VALUE&include_sub_gstd=SOME_BOOLEAN_VALUE&group_gcix=SOME_STRING_VALUE&include_sub_gcix=SOME_BOOLEAN_VALUE&group_gbix=SOME_STRING_VALUE&include_sub_gbix=SOME_BOOLEAN_VALUE&group_gcon=SOME_STRING_VALUE&include_sub_gcon=SOME_BOOLEAN_VALUE&minImportDate=SOME_STRING_VALUE&maxImportDate=SOME_STRING_VALUE&order=SOME_ARRAY_VALUE&includeQClasses=SOME_BOOLEAN_VALUE&includeRegiox=SOME_BOOLEAN_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "paging": {
    },
  • "income": 0,
  • "spending": 0,
  • "balance": 0
}

Upload transactions for categorizations etc.

Upload a set of transactions for the currently authorized user. This will create a virtual banking account for set user and start the categorization/classification.
Notes:
- For best results counterpartIban and counterpartName need to be specified
- The more information a transaction contains, the better the categorization result will be
- If you want to modify an already posted transaction, repost it with the same id/accountid

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json
required
Array of objects (Transaction)

Array of transactions

Responses

Request samples

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

Response samples

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

Delete all transactions

Delete a set, or the entirety, of transactions of the currently authorized user.

Authorizations:
cashbuzzKeyauthKey
query Parameters
maxDeletionDate
string [ 10 .. 10 ]

If specified, then only those transactions are being deleted whose 'valueDate' is equal to or earlier to the given date. The date may not be in future and must be given in the format 'YYYY-MM-DD'. If not specified, then no date limitation will be in place for the deletion.

Responses

Request samples 

curl --request DELETE \
  --url 'https://api.cashbuzz.io/v01/transactions?maxDeletionDate=SOME_STRING_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

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

Get a transaction

Get a single transaction of the user that is authorized by the access token. Must pass the transaction's identifier and the user's access token.

Authorizations:
cashbuzzKeyauthKey
path Parameters
cb_id
required
string <uuid>

Unique Identifier of transaction

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/transactions/%7Bcb_id%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": 0,
  • "cb_id": "5c5da2cd-60d0-4080-a41f-90af65b0a3dc",
  • "parentId": 0,
  • "accountId": 0,
  • "valueDate": "2020-01-31T00:00:00.000Z",
  • "bankBookingDate": "2020-01-31T00:00:00.000Z",
  • "amount": 0,
  • "purpose": "string",
  • "counterpartName": "string",
  • "counterpartAccountNumber": "string",
  • "counterpartIban": "string",
  • "counterpartBlz": "string",
  • "counterpartBic": "string",
  • "counterpartBankName": "string",
  • "counterpartMandateReference": "string",
  • "counterpartCustomerReference": "string",
  • "counterpartCreditorId": "string",
  • "counterpartDebitorId": "string",
  • "type": "string",
  • "typeCodeZka": "string",
  • "typeCodeSwift": "string",
  • "sepaPurposeCode": "string",
  • "primanota": "string",
  • "isPotentialDuplicate": true,
  • "isAdjustingEntry": true,
  • "isNew": true,
  • "importDate": "string",
  • "children": [
    ],
  • "paypalData": {
    },
  • "endToEndReference": "string",
  • "compensationAmount": 0,
  • "originalAmount": 0,
  • "differentDebitor": "string",
  • "differentCreditor": "string",
  • "bookingCurrency": "string",
  • "displayCurrency": "string",
  • "displayAmount": 0,
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627",
  • "predicted": true,
  • "qme": "string",
  • "qorg": "string",
  • "qsubject": "string",
  • "qaction": "string",
  • "group_gstd": "string",
  • "group_gcix": "string",
  • "group_gbix": "string",
  • "group_gcon": "string",
  • "group_grxx": "string",
  • "regiox": 0,
  • "external_reference": "string"
}

Delete a transaction

Delete a single transaction of the user that is authorized by the access token.

A transaction can only get deleted if at least one of the following holds true:
• The transaction belongs to a 'demo connection'
• The transaction's 'potentialDuplicate' flag is set to TRUE
• The transaction is an adjusting entry ('Zwischensaldo' transaction) that was added by cashbuzz

Note that the 'Delete all transactions' service has additional functionality and allows you to delete transactions that you cannot delete with this service.

Authorizations:
cashbuzzKeyauthKey
path Parameters
cb_id
required
string <uuid>

Unique Identifier of transaction

Responses

Request samples 

curl --request DELETE \
  --url https://api.cashbuzz.io/v01/transactions/%7Bcb_id%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "date": "string",
  • "requestId": "string",
  • "endpoint": "string",
  • "authContext": "string",
  • "bank": "string"
}

Categorization

Categorize all transactions

Upon calling this Service the (re)categorization of all transactions of the authorized user is started. This includes the recalculation of all subscriptions. With the parameter reset=true it resets all transactions first. This endpoint only returns statuscodes to the callback_uri in the message body. If your license does not allow this service, you will still recieve the http-status-code 200 regardless. For error-messages, please use the callback_uri. Please be aware that a job running for more than 15 minutes will get canceled without an error message. This happens e.g. when categorizing more than 10k transactions, please contact the support for options on handling that kind of workload.

Authorizations:
cashbuzzKeyauthKey
query Parameters
reset
boolean
Default: false

If set to true (case insensitive) the transaction analytics of that user are first reset before the analytics start otherwise the transactions are scanned incrementally. Be aware that by setting this to true, you might run into a job timeout.

categorization_only
boolean
Default: false

If set to true (case insensitive) no subscriptions will be calculated, therefore advanced options for the account like predicted transactions are invalid. The account_status will hold at 1.

subscriptions_only
boolean
Default: false

If set to true (case insensitive) only the subscriptions are recalculated, this is usefull when changing the selected status of the users accounts.

callback_uri
string

If set to anything a POST with 2000ms timeout will be send to the specified URI, please include the protocol (http/https).

volume_processing
boolean
Default: false

If set to true (case insensitive) and depending on your license, categorization will process large volumes of data quickly

Responses

Request samples 

curl --request POST \
  --url 'https://api.cashbuzz.io/v01/categorization?reset=SOME_BOOLEAN_VALUE&categorization_only=SOME_BOOLEAN_VALUE&subscriptions_only=SOME_BOOLEAN_VALUE&callback_uri=SOME_STRING_VALUE&volume_processing=SOME_BOOLEAN_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Catsaction

Categorization of transactions

This service takes the input transactions and delivers a categorization for them, returning the transactions together with the categorization attributes. The documented input parameters accountId and other id keys do not need to be filled in this call and are ignored.

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json
required
Array of objects (Transaction)

Array of transactions

Responses

Request samples

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

Response samples

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

Securities

Get and search all securities

Get securities of the user that is authorized by the access token. Must pass the user's access token. You can set optional search criteria to get only those securities that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Note: Whenever a security account is being updated, its security positions will be internally re-created, meaning that the identifier of a security position might change over time.

Authorizations:
cashbuzzKeyauthKey
query Parameters
ids
Array of integers <int64>

A comma-separated list of security identifiers. If specified, then only securities whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 1000.

search
string

If specified, then only those securities will be contained in the result whose 'name', 'isin' or 'wkn' contains the given search string (the matching works case-insensitive). If no securities contain the search string in any of these fields, then the result will be an empty list. NOTE: If the given search string consists of several terms (separated by whitespace), then ALL of these terms must be contained in the searched fields in order for a security to get included into the result.

accountIds
Array of integers <int64>

Comma-separated list of identifiers of accounts

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 500 ]
Default: 20

Maximum number of records per page. By default it's 20. Can be at most 500. NOTE: Due to its validation and visualization, the swagger frontend might show very low performance, or even crashes, when a service responds with a lot of data. It is recommended to use a HTTP client like Postman or DHC instead of our swagger frontend for service calls with large page sizes.

order
Array of strings

Determines the order of the results. You can order the results by next fields: 'id', 'name', 'isin', 'wkn', 'quote', 'quantityNominal', 'marketValue' and 'entryQuote'. The default order for all services is 'id,asc'. You can also order by multiple properties. In that case the order of the parameters passed is important. The general format is: 'property[,asc|desc]', with 'asc' being the default value. Please note that ordering by multiple fields is not supported in our swagger frontend, but you can test this feature with any HTTP tool of your choice (e.g. postman or DHC).

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/securities?ids=SOME_ARRAY_VALUE&search=SOME_STRING_VALUE&accountIds=SOME_ARRAY_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&order=SOME_ARRAY_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "securities": [
    ],
  • "paging": {
    }
}

Get a security

Get a single security for a specific user. Must pass the security's identifier and the user's access token.

Note: Whenever a security account is being updated, its security positions will be internally re-created, meaning that the identifier of a security position might change over time.

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64> [\d]+

Security identifier

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/securities/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": 0,
  • "accountId": 0,
  • "name": "string",
  • "isin": "string",
  • "wkn": "string",
  • "quote": 0,
  • "quoteCurrency": "string",
  • "quoteType": "ACTU",
  • "quoteDate": "string",
  • "quantityNominal": 0,
  • "quantityNominalType": "UNIT",
  • "marketValue": 0,
  • "marketValueCurrency": "string",
  • "entryQuote": 0,
  • "entryQuoteCurrency": "string",
  • "profitOrLoss": 0
}

Trades

Get and search all trading transactions

Get transactions of the user that is authorized by the access token. Must pass the user's access token. You can set optional search criteria to get only those trades that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
query Parameters
search
string

If specified, then only those trades will be contained in the result whose name fields contain the given search string (the matching works case-insensitive). If no trades contain the search string in name, then the result will be an empty list. NOTE: The searchstring matches exactly with whitespaces and other special characters

isin
string

If specified, then only those trades will be contained in the result whose ISIN field matches the given search string (the matching works case-insensitive). If no trades match the search string in the isin field, then the result will be an empty list. NOTE: Not all banks provide an ISIN for thier trades

wkn
string

If specified, then only those trades will be contained in the result whose wkn field matches the given search string (the matching works case-insensitive). If no trades match the search string in the wkn field, then the result will be an empty list. NOTE: Not all banks provide a wkn for thier trades

from_date
string <date>

Lower bound for a trades' date in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only trades whose 'transaction_bank_booking_date' is equal to or later than the given date will be regarded.

to_date
string <date>

Upper bound for a trades' date in the format 'YYYY-MM-DD' (e.g. '2020-01-01'). If specified, then only trades whose 'transaction_bank_booking_date' is equal to or earlier than the given date will be regarded.

min_amount
number

If specified, then only trades whose amount is equal to or greater than the given amount will be regarded. Can contain a positive or negative number with at most two decimal places. Examples: -300.12, or 90.95 Note: The currency of the security is used and not converted to EUR

max_amount
number

If specified, then only trades whose amount is equal to or less than the given amount will be regarded. Can contain a positive or negative number with at most two decimal places. Examples: -300.12, or 90.95 Note: The currency of the security is used and not converted to EUR

direction
string
Default: "all"
Enum: "all" "buy" "sell"

If specified, then only trades with the given direction(s) will be regarded. If not specified, the direction defaults to 'all'.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/trades?search=SOME_STRING_VALUE&isin=SOME_STRING_VALUE&wkn=SOME_STRING_VALUE&from_date=SOME_STRING_VALUE&to_date=SOME_STRING_VALUE&min_amount=SOME_NUMBER_VALUE&max_amount=SOME_NUMBER_VALUE&direction=SOME_STRING_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "trades": [
    ],
  • "paging": {
    },
  • "buy_volume": 0,
  • "sell_volume": 0,
  • "balance": 0
}

Get and search all trading transactions

Get transactions of the user that is authorized by the access token. Must pass the user's access token. You can set optional search criteria to get only those transactions that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
string <uuid>

Identifier of the trade

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/trades/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "accountId": 0,
  • "bankBookingDate": "2020-01-31T00:00:00.000Z",
  • "name": "string",
  • "isin": "string",
  • "wkn": "string",
  • "quote": 0,
  • "quoteCurrency": "string",
  • "quoteType": "ACTU",
  • "quantityNominal": 0,
  • "quantityNominalType": "UNIT",
  • "marketValue": 0,
  • "marketValueCurrency": "string",
  • "entryQuote": 0,
  • "entryQuoteCurrency": "string",
  • "amount": null,
  • "amountCurrency": "string"
}

Document Upload

Upload documents for different tasks

On this endpoint cashbuzz accepts different automatic document handling like:
- scanning settlements for cashbacks - automatic import of mt940 transactions and accounts Your license might not allow the usage of this endpoint.

Authorizations:
cashbuzzKeyauthKey
Request Body schema: multipart/form-data
filename
string <uuid>
filecontent
string <binary>

Responses

Request samples 

curl --request POST \
  --url https://api.cashbuzz.io/v01/documents \
  --header 'content-type: multipart/form-data' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

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

Statistics

Get statistics

Get statistics of the authorized user like the amount of redeemed cashbacks. The return data and format will frequently change due to further requirements by our clients.

Authorizations:
cashbuzzKeyauthKey

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/data \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "cashback_amounts": {
    },
  • "cashback_counts": {
    },
  • "securities_bought": {
    },
  • "securities_sold": {
    },
  • "onemarkets_bought": {
    },
  • "onemarkets_sold": {
    }
}

Subscriptions

Get and search all subscriptions

Get subscriptions of the user that is authorized by the access token. Must pass the user's access token. You can set optional search criteria to get only those subscriptions that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
query Parameters
ids
Array of strings <uuid>

A comma-separated list of subscription identifiers. If specified, then only subscriptions whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 100. Be aware, subscription identifiers are volatile.

org_id
string <uuid>

If specified, then only those subscriptions will be contained in the result whose org_id field equals the specified

classes
Array of strings

A comma-separated list of category identifiers. If specified, then the result will contain only subscriptions whose class is either one of the given classes, or - but only if the 'sub_classes' flag is set to 'true' - whose category is a sub-category of one of the given categories.

sub_classes
boolean

If specified, then the sub_classes of listed classes will be in the result

no_contracts
boolean

If specified, then only those subscriptions will be contained in the result that are not classified as contract and have a transaction_count > 1

positive_amount
boolean

If specified, then only contracts with a total_amount > 0 (true) or total_amount < 0 (false) are returned

qclasses
boolean

If your license allows it, you can set it to true to retrieve the full set of categorization options. Activating it may increase the reported costs (depending on licence). Default is false.

includeRegiox
boolean

If your license allows it, you can set it to true to retrieve the full the regionality-value of a subscription. Default is false

from_date
string <date>
Default: "1900-01-01"

Lower bound for a subscriptions' active date in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only subscriptions whose 'active time' falls into the defined time period. is equal to or later than the given date will be regarded.

to_date
string <date>
Default: "2200-01-01"

Upper bound for a subscriptions' active date in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only subscriptions whose 'active time' falls into the defined time period. is equal to or later than the given date will be regarded.

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 500 ]
Default: 20

Maximum number of records per page. Can be at most 500. NOTE: Due to its validation and visualization, the swagger frontend might show very low performance, or even crashes, when a service responds with a lot of data. It is recommended to use a HTTP client like Postman or DHC instead of our swagger frontend for service calls with large page sizes.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/subscriptions?ids=SOME_ARRAY_VALUE&org_id=SOME_STRING_VALUE&classes=SOME_ARRAY_VALUE&sub_classes=SOME_BOOLEAN_VALUE&no_contracts=SOME_BOOLEAN_VALUE&positive_amount=SOME_BOOLEAN_VALUE&qclasses=SOME_BOOLEAN_VALUE&includeRegiox=SOME_BOOLEAN_VALUE&from_date=SOME_STRING_VALUE&to_date=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "subscriptions": [
    ],
  • "paging": {
    }
}

Contracts

Get and search all contracts

Get contracts of the user that is authorized by the access token. Must pass the user's access token. You can set optional search criteria to get only those contracts that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
query Parameters
ids
Array of strings <uuid>

A comma-separated list of subscription/contract identifiers. If specified, then only subscriptions whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 100. Be aware, subscription identifiers are volatile.

org_id
string <uuid>

If specified, then only those subscriptions will be contained in the result whose org_id field equals the specified

classes
Array of strings

A comma-separated list of category identifiers. If specified, then the result will contain only subscriptions whose class is either one of the given classes, or - but only if the 'sub_classes' flag is set to 'true' - whose category is a sub-category of one of the given categories.

sub_classes
boolean

If specified, then the sub_classes of listed classes will be in the rusult

positive_amount
boolean

If specified, then only contracts with a total_amount > 0 (true) or total_amount < 0 (false) are returned

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 500 ]
Default: 20

Maximum number of records per page. Can be at most 500. NOTE: Due to its validation and visualization, the swagger frontend might show very low performance, or even crashes, when a service responds with a lot of data. It is recommended to use a HTTP client like Postman or DHC instead of our swagger frontend for service calls with large page sizes.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/contracts?ids=SOME_ARRAY_VALUE&org_id=SOME_STRING_VALUE&classes=SOME_ARRAY_VALUE&sub_classes=SOME_BOOLEAN_VALUE&positive_amount=SOME_BOOLEAN_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "contracts": [
    ],
  • "paging": {
    }
}

Invoices

Get and search all invoices

Retrieves all invoices of a user

Authorizations:
cashbuzzKeyauthKey

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/invoices \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

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

Create a new invoice

Create a new invoice for the prediction engine and track its payment status.

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json
id
string <uuid>

Unique identifier of an invoice

org_id
string <uuid>

Unique identifier of an organization

org_name
string

Name of an organization in the database

custom_org_name
string

Custom Name of an organization

object (Address)

Addressdata in the GeoJSON format

object (Address)

Addressdata in the GeoJSON format

invoice_date
required
string

Invoice date in the format 'YYYY-MM-DD'

due_date
string

Due date in the format 'YYYY-MM-DD'

payment_date
string

Payment date in the format 'YYYY-MM-DD'

gross_amount
required
number

Gross amount of the invoice

net_amount
number

Net amount of the invoice

invoice_ident
required
string

Invoice identifier as defined by the user

customer_ident
string

Customer identifier as defined by the user

ibans
string

Counterpart IBANs

is_creditor
boolean

True if the user is the creditor

payment_transaction
string <uuid>

Identifier of the transaction that payed the invoice

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "string",
  • "custom_org_name": "string",
  • "address": {
    },
  • "custom_address": {
    },
  • "invoice_date": "2020-01-01T00:00:00.000Z",
  • "due_date": "2020-01-01T00:00:00.000Z",
  • "payment_date": "2020-01-01T00:00:00.000Z",
  • "gross_amount": 0,
  • "net_amount": 0,
  • "invoice_ident": "string",
  • "customer_ident": "string",
  • "ibans": "string",
  • "is_creditor": true,
  • "payment_transaction": "e7207acb-9c5c-414c-9076-8b271293a748"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_description": "string"
}

Delete all invoices

Deletes all invoices for authorized user

Authorizations:
cashbuzzKeyauthKey

Responses

Request samples 

curl --request DELETE \
  --url https://api.cashbuzz.io/v01/invoices \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

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

Get a single invoice

Retrieves a single invoice

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
string <uuid>

Identifier of requested Organization

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/invoices/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "string",
  • "custom_org_name": "string",
  • "address": {
    },
  • "custom_address": {
    },
  • "invoice_date": "2020-01-01T00:00:00.000Z",
  • "due_date": "2020-01-01T00:00:00.000Z",
  • "payment_date": "2020-01-01T00:00:00.000Z",
  • "gross_amount": 0,
  • "net_amount": 0,
  • "invoice_ident": "string",
  • "customer_ident": "string",
  • "ibans": "string",
  • "is_creditor": true,
  • "payment_transaction": "e7207acb-9c5c-414c-9076-8b271293a748"
}

Delete a single invoice

Deletes a single invoice

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
string <uuid>

Identifier of requested Organization

Responses

Request samples 

curl --request DELETE \
  --url https://api.cashbuzz.io/v01/invoices/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_description": "string"
}

Modify an existing invoice

Updates a single invoices data

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
string <uuid>

Identifier of requested Organization

Request Body schema: application/json
id
string <uuid>

Unique identifier of an invoice

org_id
string <uuid>

Unique identifier of an organization

org_name
string

Name of an organization in the database

custom_org_name
string

Custom Name of an organization

object (Address)

Addressdata in the GeoJSON format

object (Address)

Addressdata in the GeoJSON format

invoice_date
required
string

Invoice date in the format 'YYYY-MM-DD'

due_date
string

Due date in the format 'YYYY-MM-DD'

payment_date
string

Payment date in the format 'YYYY-MM-DD'

gross_amount
required
number

Gross amount of the invoice

net_amount
number

Net amount of the invoice

invoice_ident
required
string

Invoice identifier as defined by the user

customer_ident
string

Customer identifier as defined by the user

ibans
string

Counterpart IBANs

is_creditor
boolean

True if the user is the creditor

payment_transaction
string <uuid>

Identifier of the transaction that payed the invoice

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "string",
  • "custom_org_name": "string",
  • "address": {
    },
  • "custom_address": {
    },
  • "invoice_date": "2020-01-01T00:00:00.000Z",
  • "due_date": "2020-01-01T00:00:00.000Z",
  • "payment_date": "2020-01-01T00:00:00.000Z",
  • "gross_amount": 0,
  • "net_amount": 0,
  • "invoice_ident": "string",
  • "customer_ident": "string",
  • "ibans": "string",
  • "is_creditor": true,
  • "payment_transaction": "e7207acb-9c5c-414c-9076-8b271293a748"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "string",
  • "custom_org_name": "string",
  • "address": {
    },
  • "custom_address": {
    },
  • "invoice_date": "2020-01-01T00:00:00.000Z",
  • "due_date": "2020-01-01T00:00:00.000Z",
  • "payment_date": "2020-01-01T00:00:00.000Z",
  • "gross_amount": 0,
  • "net_amount": 0,
  • "invoice_ident": "string",
  • "customer_ident": "string",
  • "ibans": "string",
  • "is_creditor": true,
  • "payment_transaction": "e7207acb-9c5c-414c-9076-8b271293a748"
}

Users

Create a new user/login user

Create a new user -- Must pass your global (i.e. client) access token. The automatic update of the user's bank connections is disabled by default for any new user. User identifiers are regarded case-insensitive by cashbuzz. Please note that cashbuzz generally has a restricted set of allowed characters for input fields.
Login user -- pass user credentials and your access token, make sure to set the correct value for the login-field.
When creating a User, you can either specify an email-address, depeding on your licence settings users will receive a validation eMail. If you use the username they won't receive that eMail.
When using the user/password variant to login, any existing authkey will get invalidated, to keep the old authorization-key and just refresh it's validity period.

Authorizations:
cashbuzzKeyauthKey
query Parameters
login
required
boolean

Set to true if you want to login an existing user, set to false if you want to create a user. Be aware, that a new password login invalidates an authkey before creating a new one.

campaign
string <uuid>

if the user is onboarding using a specific Cashback-Campaign, set the campaignId header.

Request Body schema: application/json

User's details

id
string[a-zA-Z0-9\-_\.\+@]application/json

User's identifier. Max length is 36 symbols.

password
string

User's password. Minimum length is 6, and maximum length is 36.

refreshtoken
string

Instead of username/password you can use the refreshtoken to lengthen the validity of the authorization key.

email
string[A-Za-z0-9¡-ʯ &\(\)\{\}\[\]\.:,;\?!\+\-_\$@...

User's email address. Maximum length is 320.

username
string

User's login name. Maximum length is 320.

phone
string[A-Za-z0-9¡-ʯ &\(\)\{\}\[\]\.:,;\?!\+\-_\$@...

User's phone number. Maximum length is 50.

birthday
string <date>

Birthday of the logged in user, required for cashbacks

firstname
string

User's first name

lastname
string

User's last name

address
string

User's address, required for cashbacks, the format is 'street;housenumber;zipcode;city;country'

currency
string

The currency code see ISO 4217

language
string

The language code see ISO 639-2-Codes

tosaccepted
boolean

Required when creating a user, without the acceptance of our ToS no user will be created.

token
string

If your API-Key allows login/create user with a specific Token-Process you can set that token here.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "password": "string",
  • "refreshtoken": "string",
  • "email": "string",
  • "username": "string",
  • "phone": "string",
  • "birthday": "2019-08-24",
  • "firstname": "string",
  • "lastname": "string",
  • "address": "string",
  • "currency": "string",
  • "language": "string",
  • "tosaccepted": true,
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "password": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "authkey": "string",
  • "refreshtoken": "string",
  • "birthday": "2019-08-24",
  • "firstname": "string",
  • "lastname": "string",
  • "address": "string",
  • "currency": "string",
  • "language": "string"
}

Request a new password

Request a new password, must pass the User's eMail-address

Authorizations:
cashbuzzKeyauthKey
query Parameters
email
string

The user's e-Mail address

Responses

Request samples 

curl --request POST \
  --url 'https://api.cashbuzz.io/v01/users/requestNewPassword?email=SOME_STRING_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

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

Get the user with userId

Get the users general Data, this is mainly used to debug singular cashback Events

Authorizations:
cashbuzzKeyauthKey
path Parameters
userId
required
string

User's identifier

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/users/%7BuserId%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "password": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "authkey": "string",
  • "refreshtoken": "string",
  • "birthday": "2019-08-24",
  • "firstname": "string",
  • "lastname": "string",
  • "address": "string",
  • "currency": "string",
  • "language": "string"
}

Users/me

validate the authorized user with the validation code he provided

If the system that is used to create the User does not provide verified eMail-addresses, the user gets an eMail from cashbuzz with a verification code. This endpoint is used to provide the data.

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json
validationcode
required
string

the validation code send to the users eMail

Responses

Request samples

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

Response samples

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

Get the authorized user

Get the authorized user's data. Must pass the user's access token. Only the authorized user can get his data, i.e. his access token must be used (in header). This service returns the user's password as 'XXXXX'.

Authorizations:
cashbuzzKeyauthKey

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/users/me \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "password": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "authkey": "string",
  • "refreshtoken": "string",
  • "birthday": "2019-08-24",
  • "firstname": "string",
  • "lastname": "string",
  • "address": "string",
  • "currency": "string",
  • "language": "string"
}

Delete the authorized user

Delete the authorized user. Must pass the user's access token. ATTENTION: This deletes the user including all of his bank connections, accounts, balance data and transactions! THIS PROCESS CANNOT BE UNDONE! Note that a user cannot get deleted while any of his bank connections are currently busy (in the process of import, update, or transactions categorization).

Authorizations:
cashbuzzKeyauthKey

Responses

Request samples 

curl --request DELETE \
  --url https://api.cashbuzz.io/v01/users/me \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_description": "string"
}

Edit the authorized user

Edit the authorized user's data and settings. Must pass the user's access token. Pass an empty string (but not null) to unset any field. At least one field must have a non-null value in the request body. This service returns the user's password as 'XXXXX'. If this is called with an empty body the validation eMail will be send again.

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json

User's details

id
string[a-zA-Z0-9\-_\.\+@]application/json

User's identifier. Max length is 36 symbols.

password
string

User's password. Minimum length is 6, and maximum length is 36.

refreshtoken
string

Instead of username/password you can use the refreshtoken to lengthen the validity of the authorization key.

email
string[A-Za-z0-9¡-ʯ &\(\)\{\}\[\]\.:,;\?!\+\-_\$@...

User's email address. Maximum length is 320.

username
string

User's login name. Maximum length is 320.

phone
string[A-Za-z0-9¡-ʯ &\(\)\{\}\[\]\.:,;\?!\+\-_\$@...

User's phone number. Maximum length is 50.

birthday
string <date>

Birthday of the logged in user, required for cashbacks

firstname
string

User's first name

lastname
string

User's last name

address
string

User's address, required for cashbacks, the format is 'street;housenumber;zipcode;city;country'

currency
string

The currency code see ISO 4217

language
string

The language code see ISO 639-2-Codes

tosaccepted
boolean

Required when creating a user, without the acceptance of our ToS no user will be created.

token
string

If your API-Key allows login/create user with a specific Token-Process you can set that token here.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "password": "string",
  • "refreshtoken": "string",
  • "email": "string",
  • "username": "string",
  • "phone": "string",
  • "birthday": "2019-08-24",
  • "firstname": "string",
  • "lastname": "string",
  • "address": "string",
  • "currency": "string",
  • "language": "string",
  • "tosaccepted": true,
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "password": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "authkey": "string",
  • "refreshtoken": "string",
  • "birthday": "2019-08-24",
  • "firstname": "string",
  • "lastname": "string",
  • "address": "string",
  • "currency": "string",
  • "language": "string"
}

logout the user

logout a user. Must pass your global (i.e. client) access token.

Authorizations:
cashbuzzKeyauthKey

Responses

Request samples 

curl --request POST \
  --url https://api.cashbuzz.io/v01/users/me/logout \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "date": "string",
  • "requestId": "string",
  • "endpoint": "string",
  • "authContext": "string",
  • "bank": "string"
}

Execute password change

Change the password of a user. Must pass the change-token provided to the user by eMail or the requestChange-Endpoint. This Endpoint does not require the Authorization-Header!

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json
email
required
string[a-zA-Z0-9\-_\.\+@]application/json

Users eMail-address

password
required
string[A-Za-z0-9¡-ʯ &\(\)\{\}\[\]\.:,;\?!\+\-_\$@...

User's new password. Minimum length is 6, and maximum length is 36.

changeToken
required
string

The Changetoken the user got by Mail or the requestChange-Endpoint provided

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "changeToken": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "date": "string",
  • "requestId": "string",
  • "endpoint": "string",
  • "authContext": "string",
  • "bank": "string"
}

Execute eMail Change

Change the eMail of a user. Must pass the change-token provided to the user by eMail or the requestChange-Endpoint

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json
newemail
required
string[a-zA-Z0-9\-_\.\+@]application/json

User identifier

email
required
string[a-zA-Z0-9\-_\.\+@]application/json

User identifier

changeToken
required
string

The Changetoken the user got by Mail or the requestChange-Endpoint provided

Responses

Request samples

Content type
application/json
{
  • "newemail": "string",
  • "email": "string",
  • "changeToken": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "date": "string",
  • "requestId": "string",
  • "endpoint": "string",
  • "authContext": "string",
  • "bank": "string"
}

Request change

Request password or eMail change for a user. Must pass your user-credentials. Note that cashbuzz regards user identifiers case insensitive.

Authorizations:
cashbuzzKeyauthKey
Request Body schema: application/json
email
required
string[a-zA-Z0-9\-_\.\+@]application/json

Users eMail-address

password
required
string

The Users password

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "userEmail": "string",
  • "passwordChangeToken": "string"
}

Users/affinities

Get all the affinities of the user

Get the authorized user's affinities. Must pass the user's access token. Only the authorized user can get his data, i.e. his access token must be used (in header). The availability of this service is dependent on your license. If a specific month is provided, only affinities for that month are returned. Note that for a date interval, either from_date or to_date may be null. If both dates are null, then the time interval is not set, and only the current value of the attribute is returned.

Authorizations:
cashbuzzKeyauthKey
query Parameters
month
integer

Specific month to evaluate cyclic behavior

class
string

Return the affinities of the logged in user for the requested class.

sub_classes
boolean

If a class is provided, you can use this option to return all the affinities of subclasses too.

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 1000 ]
Default: 200

Maximum number of records per page. By default it's 200. Can be at most 1000.

order
Array of strings

Determines the order of the results. You can order the results by next fields: 'class', 'month' and 'affinity'. The default order for all services is 'class,asc'. You can also order by multiple properties. In that case the order of the parameters passed is important. The general format is: 'property[,asc|desc]', with 'asc' being the default value.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/users/affinities?month=SOME_INTEGER_VALUE&class=SOME_STRING_VALUE&sub_classes=SOME_BOOLEAN_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&order=SOME_ARRAY_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "affinities": [
    ],
  • "paging": {
    }
}

Users/attributes

Get all the attributes of the user

Get the authorized user's attributes. Must pass the user's access token. Only the authorized user can get his data, i.e. his access token must be used (in header). The availability of this service is dependent on your license. If a date interval is provided, there will be a list of values returned for each applicable attribute in the form date  value so the caller sees when the value of the attribute has changed. Note that for a date interval, either from_date or to_date may be null. If both dates are null, then the time interval is not set, and only the current value of the attribute is returned.

Authorizations:
cashbuzzKeyauthKey
query Parameters
from_date
string <date>

Lower bound for an attribute's date in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only attributes whose 'date_valid_from' is equal to or later than the given date will be regarded.

to_date
string <date>

Upper bound for an attribute's date in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only attributes whose 'date_valid_to' is equal to or earlier than the given date will be regarded.

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 1000 ]
Default: 200

Maximum number of records per page. By default it's 200. Can be at most 1000.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/users/attributes?from_date=SOME_STRING_VALUE&to_date=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "attribute_groups": [
    ],
  • "paging": {
    }
}

Get one attribute of the user

Get the authorized user's attribute. Must pass the user's access token. Only the authorized user can get his data, i.e. his access token must be used (in header). The availability of this service is dependent on your license. You may either request a single attribute, an attribute_group or a whole attribute section. If a date interval is provided, there will be a list of values returned for each applicable attribute in the form date  value so the caller sees when the value of the attribute has changed. Note that for a date interval, either from_date or to_date may be null. If both dates are null, then the time interval is not set, and only the latest entry of the requested attributes will be returned.

Authorizations:
cashbuzzKeyauthKey
path Parameters
section
required
string

Identifying section of the requested attribute

group
required
string

Identifying group of the requested attribute

name
required
string

Identifying name of the requested attribute

query Parameters
from_date
string <date>

Lower bound for an attribute's date in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only attributes whose 'date_valid_from' is equal to or later than the given date will be regarded.

to_date
string <date>

Upper bound for an attribute's date in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only attributes whose 'date_valid_to' is equal to or earlier than the given date will be regarded.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/users/attributes/%7Bsection%7D/%7Bgroup%7D/%7Bname%7D?from_date=SOME_STRING_VALUE&to_date=SOME_STRING_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "section": "string",
  • "attributes": [
    ]
}

Users/finance_groups

Get all the finance groups of the user

Get the authorized user's finance groups content. Must pass the user's access token. Only the authorized user can get his data, i.e. his access token must be used (in header). The availability of this service is dependent on your license. If a month interval is provided, there will be a list of values returned for each applicable finance group . Note that for a month interval, either from_month or to_month may be null. If both dates are null, then the time interval is not set, and only the current value of the attribute is returned. To get the finance groups of a single month set from_month and to_month to said month.

Authorizations:
cashbuzzKeyauthKey
query Parameters
fgroup
required
string

Select the finance group you want to get summarized.

from_month
string

Lower bound for a finance_group's month in the format 'YYYY-MM' (e.g. '2016-01'). If specified, then only finance_group entries whose 'month' is equal to or later than the given month will be regarded.

to_month
string

Upper bound for a finance_group's month in the format 'YYYY-MM' (e.g. '2016-01'). If specified, then only finance_group entries whose 'month' is equal to or earlier than the given month will be regarded.

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 1000 ]
Default: 200

Maximum number of records per page. By default it's 200. Can be at most 1000.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/users/f_groups?fgroup=SOME_STRING_VALUE&from_month=SOME_STRING_VALUE&to_month=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "finance_groups": [
    ],
  • "paging": {
    }
}

Users/insights

Retrieve insights

As soon as the full categorization is done, insights about the user can be retrieved. For a list of all possible insights, GET /descriptions/insights. Please check Programmable Insights for further information. The avaibilty of this enpoint depends on your license

Authorizations:
cashbuzzKeyauthKey
path Parameters
section
required
string

Identifying section of the requested insight

group
required
string

Identifying group of the requested insight

name
required
string

Identifying name of the requested insight

query Parameters
start_date
string <date>

Lower bound for a insight calculation in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). Be aware, that the quantization is based on the calendar not the start_date, so it might start with a patial period. Default value is today - 3 months.

end_date
string <date>

Upper bound for a insight calculation in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). Be aware, that the quantization is based on the calendar not the to_date, so it might end with a patial period. Default value is today.

quantization
string
Default: "month"
Enum: "year" "quarter" "month" "week" "day"

Quantization of the insight function, start and end of a quant are based on the calendar not on a time period set by fetching the insight.

class
string 4 characters

If required by the requested insight it can be used to set to a specific class

sub_classes
boolean
Default: false

If a class is provided, you can use this option to return all the affinities of subclasses too.

vat_modified
boolean
Default: false

If required by the requested insight it can be used to control whether amounts are modified by the corresponding VAT amounts

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/insights/%7Bsection%7D/%7Bgroup%7D/%7Bname%7D?start_date=SOME_STRING_VALUE&end_date=SOME_STRING_VALUE&quantization=SOME_STRING_VALUE&class=SOME_STRING_VALUE&sub_classes=SOME_BOOLEAN_VALUE&vat_modified=SOME_BOOLEAN_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "date": "2020-01-31T00:00:00.000Z",
  • "value": 0,
  • "start_date": "2020-01-31T00:00:00.000Z",
  • "end_date": "2020-01-31T00:00:00.000Z"
}

Create insight function

As soon as the full categorization is done, insights about the user can be retrieved. For a list of all possible insights, GET /descriptions/insights. Please check Programmable Insights for further information. To update an insight statement, post the updated statement on the same path. The avaibilty of this enpoint depends on your license.

Authorizations:
cashbuzzKeyauthKey
path Parameters
section
required
string[a-zA-Z0-9]

Identifying section of the requested insight

group
required
string[a-zA-Z0-9]

Identifying group of the requested insight

name
required
string[a-zA-Z0-9]

Identifying name of the requested insight

Request Body schema: application/json
insight_section
required
string

insight section

insight_group
required
string

insight group

insight_name
required
string

insight name

statement
required
string

The insight calculation statement

title_en
required
string

English label of the insight

title_de
required
string

German label of the insight

description
required
string

Description of the insight.

result_type
required
string
Enum: "value" "series"

Whether the insight will return a date-value series or a single value

value_type
required
string
Enum: "int" "float" "uuid" "text" "bool"

What type of values will be returned.

display_type
required
string <= 128

Optional, how a frontend should display the result. Free text

multiply_values_by_n1
required
boolean

Whether the value should be multiplied by negative 1

text_en
required
string <= 4096

English text to display on the insight.

text_de
required
string <= 4096

German text to display on the insight.

unit_en
required
string

English unit to display on the insight.

unit_de
required
string

German unit to display on the insight.

value_format
required
string

How the value should be formatted

value_color
required
string

What color the value of the insight should have.

order_nr
required
integer

Optional ordering of the insight

icon
required
string

Optional icon to display on the insight.

icon_color
required
string

Optional coloring of an svg icon

Responses

Request samples

Content type
application/json
{
  • "insight_section": "string",
  • "insight_group": "string",
  • "insight_name": "string",
  • "statement": "string",
  • "title_en": "string",
  • "title_de": "string",
  • "description": "string",
  • "result_type": "value",
  • "value_type": "int",
  • "display_type": "string",
  • "multiply_values_by_n1": true,
  • "text_en": "string",
  • "text_de": "string",
  • "unit_en": "string",
  • "unit_de": "string",
  • "value_format": "string",
  • "value_color": "string",
  • "order_nr": 0,
  • "icon": "string",
  • "icon_color": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "date": "string",
  • "requestId": "string",
  • "endpoint": "string",
  • "authContext": "string",
  • "bank": "string"
}

Modify insight function

Modify an existing insight

Authorizations:
cashbuzzKeyauthKey
path Parameters
section
required
string[a-zA-Z0-9]

Identifying section of the requested insight

group
required
string[a-zA-Z0-9]

Identifying group of the requested insight

name
required
string[a-zA-Z0-9]

Identifying name of the requested insight

Request Body schema: application/json
insight_section
required
string

insight section

insight_group
required
string

insight group

insight_name
required
string

insight name

statement
required
string

The insight calculation statement

title_en
required
string

English label of the insight

title_de
required
string

German label of the insight

description
required
string

Description of the insight.

result_type
required
string
Enum: "value" "series"

Whether the insight will return a date-value series or a single value

value_type
required
string
Enum: "int" "float" "uuid" "text" "bool"

What type of values will be returned.

display_type
required
string <= 128

Optional, how a frontend should display the result. Free text

multiply_values_by_n1
required
boolean

Whether the value should be multiplied by negative 1

text_en
required
string <= 4096

English text to display on the insight.

text_de
required
string <= 4096

German text to display on the insight.

unit_en
required
string

English unit to display on the insight.

unit_de
required
string

German unit to display on the insight.

value_format
required
string

How the value should be formatted

value_color
required
string

What color the value of the insight should have.

order_nr
required
integer

Optional ordering of the insight

icon
required
string

Optional icon to display on the insight.

icon_color
required
string

Optional coloring of an svg icon

Responses

Request samples

Content type
application/json
{
  • "insight_section": "string",
  • "insight_group": "string",
  • "insight_name": "string",
  • "statement": "string",
  • "title_en": "string",
  • "title_de": "string",
  • "description": "string",
  • "result_type": "value",
  • "value_type": "int",
  • "display_type": "string",
  • "multiply_values_by_n1": true,
  • "text_en": "string",
  • "text_de": "string",
  • "unit_en": "string",
  • "unit_de": "string",
  • "value_format": "string",
  • "value_color": "string",
  • "order_nr": 0,
  • "icon": "string",
  • "icon_color": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "date": "string",
  • "requestId": "string",
  • "endpoint": "string",
  • "authContext": "string",
  • "bank": "string"
}

Delete insight

Delete a created insight function

Authorizations:
cashbuzzKeyauthKey
path Parameters
section
required
string

Identifying section of the requested insight

group
required
string

Identifying group of the requested insight

name
required
string

Identifying name of the requested insight

Responses

Request samples 

curl --request DELETE \
  --url https://api.cashbuzz.io/v01/insights/%7Bsection%7D/%7Bgroup%7D/%7Bname%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "date": "string",
  • "requestId": "string",
  • "endpoint": "string",
  • "authContext": "string",
  • "bank": "string"
}

Daily Hints

Get all hints

Get hints for the user that is authorized by the access token. Must pass the user's access token. You can set optional search criteria to get only those hints that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
query Parameters
is_relevant
boolean

if True, only hints that are currently relevant are returned

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 1000 ]
Default: 200

Maximum number of records per page. Can be at most 1000.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/suggestions?is_relevant=SOME_BOOLEAN_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "descriptionsclass": [
    ],
  • "paging": {
    }
}

Event Tracking

Create a new log entry to track something

Logs all the things send to him, some of the standard events are: 'cb_user_created': User created within Cashbuzz platform 'cb_user_deleted': User deleted within Cashbuzz platform 'cb_tospp_accepted': User has passed Terms of Service / Privacy Policy 'cb_bank_connection_requested': Bank connection requested, i.e. finAPI form passed by user 'cb_bank_connection_established': Successful bank connection established for user using this API endpoint it is possible to track user behavior and log certain events for future analytics. This Endpoint is special, because it can be used without an Authorization-Key, without an authkey the record lacks the user identification.

Authorizations:
cashbuzzKeyauthKey
query Parameters
name
required
string

The event you want to track, see the list in description for suggestions. Some events are tracked without using this endpoint.

attributes
required
string

Additional information of that event like who requested the event.

campaign
string <uuid>

if the user is onboarding using a specific Cashback-Campaign, set the campaignId header.

Responses

Request samples 

curl --request POST \
  --url 'https://api.cashbuzz.io/v01/events?name=SOME_STRING_VALUE&attributes=SOME_STRING_VALUE&campaign=SOME_STRING_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "date": "string",
  • "requestId": "string",
  • "endpoint": "string",
  • "authContext": "string",
  • "bank": "string"
}

Cashbacks

Get and search all cashbacks

Get and search redeemable cashbacks from cashbuzzÔÇÖ database. Must pass the authorized user's access token. (later-- You may set optional search criteria to get only those cashbacks that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
query Parameters
ids
Array of integers <int64>

A comma-separated list of cashback identifiers. If specified, then only cashbacks whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 1000.

search
string

If specified, then only those cashbacks will be contained in the result whose 'partnername' or 'category' contains the given search string (the matching works case-insensitive). If no cashbacks contain the search string in any of the regarded fields, then the result will be an empty list.

isRedeemed
boolean

If specified, then only redeemed (in case of 'true' value) or unredeemed (in case of 'false' value) cashbacks will be regarded.

isRejected
boolean

If specified, then only those cashbacks will be regarded that have the given value (true or false) for their 'rejected' field.

statusCode
integer

If specified, then only those cashbacks will be regarded that have the given statusCode

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 500 ]
Default: 20

Maximum number of records per page. Can be at most 500

order
Array of strings

Determines the order of the results. You can order the results by 'id', 'partnername', 'category' or 'popularity'. The default order for all services is 'id,asc'. You can also order by multiple properties. In that case the order of the parameters passed is important. Example: '/cashbacks?order=partnername,desc&order=id,asc' will return cashbacks ordered by 'partnername' (descending), where cashbacks from the same 'partnername' are ordered by 'id' (ascending). The general format is: 'property[,asc|desc]', with 'asc' being the default value.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/cashbacks?ids=SOME_ARRAY_VALUE&search=SOME_STRING_VALUE&isRedeemed=SOME_BOOLEAN_VALUE&isRejected=SOME_BOOLEAN_VALUE&statusCode=SOME_INTEGER_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&order=SOME_ARRAY_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "cashbacks": [
    ],
  • "paging": {
    }
}

Get Information about the cashback

Get Information about the cashback

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64>

identifier of the cashback

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/cashbacks/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "partnerId": 0,
  • "rewardText": "string",
  • "statusCode": 0,
  • "tosppStatus": 0,
  • "campaignId": 0,
  • "reward": "string",
  • "currency": "string",
  • "email": "user@example.com"
}

Initialize a cashback with the cashback ID

Initialize a cashback with the cashback ID

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64>

identifier of the cashback

Responses

Request samples 

curl --request POST \
  --url https://api.cashbuzz.io/v01/cashbacks/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

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

Vouchers

Get and search all vouchers

Get and search redeemable vouchers from cashbuzzÔÇÖ database. Must pass the authorized user's access token. (later-- You may set optional search criteria to get only those vouchers that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
query Parameters
ids
Array of integers <int64>

A comma-separated list of voucher identifiers. If specified, then only vouchers whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 1000.

search
string

If specified, then only those vouchers will be contained in the result whose 'partnername' contains the given search string (the matching works case-insensitive). If no vouchers contain the search string in any of the regarded fields, then the result will be an empty list.

category
integer

If specified, then only those vouchers will be contained in the result whose 'category' equals the given category-id. If no vouchers are in that category, then the result will be an empty list.

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 500 ]
Default: 20

Maximum number of records per page. Can be at most 500

order
Array of strings

Determines the order of the results. You can order the results by 'id', 'shopname', 'category' or 'popularity'. The default order for all services is 'id,asc'. You can also order by multiple properties. In that case the order of the parameters passed is important. Example: '/vouchers?order=partnername,desc&order=id,asc' will return vouchers ordered by 'partnername' (descending), where vouchers from the same 'partnername' are ordered by 'id' (ascending). The general format is: 'property[,asc|desc]', with 'asc' being the default value.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/vouchers?ids=SOME_ARRAY_VALUE&search=SOME_STRING_VALUE&category=SOME_INTEGER_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&order=SOME_ARRAY_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "vouchers": [
    ],
  • "paging": {
    }
}

Get Information about the voucher

Get Information about the voucher

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64>

identifier of the voucher

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/vouchers/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "shopName": "string",
  • "shopId": "string",
  • "voucherText": "string",
  • "longDescription": "string",
  • "category": "string",
  • "language": "string",
  • "voucherType": 0,
  • "code": "string",
  • "uri": "string",
  • "reward": 0,
  • "logoPath": "string"
}

Initialize a voucher-transaction with the voucher

Initialize a voucher-transaction with the voucher ID, used for tracking

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64>

identifier of the voucher

Responses

Request samples 

curl --request POST \
  --url https://api.cashbuzz.io/v01/vouchers/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": "string",
  • "shopId": "string",
  • "uri": "string"
}

Retention Partners

Get and search the retention partner list

Get and search partners from cashbuzzÔÇÖ database of partners. Must pass the authorized user's access token, or your client's access token. You can set optional search criteria to get only those partners that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.

Authorizations:
cashbuzzKeyauthKey
query Parameters
ids
Array of integers <int64>

A comma-separated list of partner identifiers. If specified, then only partners whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 100.

search
string

If specified, then only those retention partners will be contained in the result whose 'name', 'category' or 'city' contains the given search string (the matching works case-insensitive). If no partners contain the search string in any of the regarded fields, then the result will be an empty list. Note that if the given search string consists of several terms (separated by whitespace), then ALL of these terms must apply to a partner in order for it to get included into the result.

country
Array of strings

Comma-separated list of two-letter country codes (ISO 3166 ALPHA-2). If set, then only those partners will be regarded in the search that are located in the specified countries. Notes that partners which do not have a location set (i.e. international companies) will ALWAYS be regarded in the search, independent of what you specify for this field. When you pass a country code that doesn't exist in the ISO 3166 ALPHA-2 standard, then the service will respond with 400 BAD_REQUEST.

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 500 ]
Default: 20

Maximum number of records per page. Can be at most 500.

order
Array of strings

Determines the order of the results. You can order the results by 'id', 'name' or 'category'. The default order for all services is 'id,asc'. You can also order by multiple properties. In that case the order of the parameters passed is important. Example: '/partners?order=name,desc&order=id,asc' will return the retention partners ordered by 'name' (descending), where partners with the same 'name' are ordered by 'id' (ascending). The general format is: 'property[,asc|desc]', with 'asc' being the default value.

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/partners?ids=SOME_ARRAY_VALUE&search=SOME_STRING_VALUE&country=SOME_ARRAY_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE&order=SOME_ARRAY_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "partners": [
    ],
  • "paging": {
    }
}

Get a retention partners information

Get a single retention Partner from cashbuzzÔÇÖ database of partners. You have to pass the partners identifier and your client's access token.

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64> [\d]+

Identifier of requested Partner

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/partners/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "squaredLogo": "string",
  • "bigLogo": "string",
  • "longDescription": "string",
  • "termsOfService": "string",
  • "privacyPolicy": "string"
}

Accept the partners TOS/TOR and PP

Accept the partners TOS or TOR and PP in its current version, if there is an update the user will have to reaccept

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
integer <int64> [\d]+

id of the retention partner

Responses

Request samples 

curl --request POST \
  --url https://api.cashbuzz.io/v01/partners/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "date": "string",
  • "requestId": "string",
  • "endpoint": "string",
  • "authContext": "string",
  • "bank": "string"
}

Cashbuzz

getLegalData

Get Information about cashbuzz, like the GDP, TOSPP and support eMails.

Authorizations:
cashbuzzKeyauthKey
query Parameters
partner
integer >= 0
Default: 0

Result holds the legal data of the partner you want to retrieve

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/cashbuzz?partner=SOME_INTEGER_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "tospp": "string",
  • "gdp": "string",
  • "logo": "string",
  • "icon": "string",
  • "impressum": "string",
  • "contact": "string"
}

Accept the cashbuzz TOS/GDP in its current version

Accept the cashbuzz TOS/GDP in its current version, if there is an update the user will have to reaccept

Authorizations:
cashbuzzKeyauthKey

Responses

Request samples 

curl --request POST \
  --url https://api.cashbuzz.io/v01/cashbuzz \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "date": "string",
  • "requestId": "string",
  • "endpoint": "string",
  • "authContext": "string",
  • "bank": "string"
}

Descriptions

Get all classes

Get a description of all classes that are available to you (depending on your license).

Authorizations:
cashbuzzKeyauthKey
query Parameters
page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 500 ]
Default: 20

Maximum number of records per page. Can be at most 500

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/descriptions/classes?page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "qclasses": [
    ],
  • "paging": {
    }
}

Get a single class

Get the information about a single class, if it's available to you (depending on your license).

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
string

Identifier of class

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/descriptions/classes/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "label": "string",
  • "label_path": "string",
  • "label_de": "string",
  • "label_en": "string",
  • "order_nr": 0,
  • "logo": "string",
  • "logo_sqrd": "string",
  • "description": "string",
  • "expanded": "string"
}

Get all attributes

Get all attribute descriptions, that are available to you (depending on your license).

Authorizations:
cashbuzzKeyauthKey

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/descriptions/attributes \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "attributes": [
    ],
  • "paging": {
    }
}

Get attribute descriptions

Get an attribute description, if it's available to you (depending on your license).

Authorizations:
cashbuzzKeyauthKey
path Parameters
section
required
string

Identifying section of the requested attribute description

group
required
string

Identifying group of the requested attribute description

name
required
string

Identifying name of the requested attribute description

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/descriptions/attributes/%7Bsection%7D/%7Bgroup%7D/%7Bname%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "name": "string",
  • "group": "string",
  • "section": "string",
  • "type": "string",
  • "description": "string",
  • "name_en": "string",
  • "name_de": "string",
  • "group_en": "string",
  • "group_de": "string",
  • "section_en": "string",
  • "section_de": "string",
  • "order_number": 0
}

Get organization information

Get detailed information on single organization. You have to pass the organizations identifier. Some information may only be provided if you have an extended organzation API license. This endpoint can be overloaded by providing a list of ids, seperated by commas and enclosed in normal brackets. For example /descriptions/organizations/(00000000-0000-0000-0000-000000000000,00000000-0000-0000-0000-000000000001,00000000-0000-0000-0000-000000000002) In that case, the response is a list of organization descriptions.

Authorizations:
cashbuzzKeyauthKey
path Parameters
id
required
string <uuid>

Identifier of requested Organization

Responses

Request samples 

curl --request GET \
  --url https://api.cashbuzz.io/v01/descriptions/organizations/%7Bid%7D \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "full_name": "string",
  • "legal_name": "string",
  • "brand_name": "string",
  • "uri": "string",
  • "address": "string",
  • "phone_number": "string",
  • "generic": true,
  • "rating_color": "white",
  • "esg_rating_color": "white",
  • "qorg": "string",
  • "logo": "string",
  • "logo_sqrd": "string",
  • "code_nace_rev2": "string"
}

Get all available insights

Get a description of all insights that are available to you including your own defined insights and the preconfigured.

Authorizations:
cashbuzzKeyauthKey
query Parameters
section
string

Identifying section of the requested insight description

group
string

Identifying group of the requested insight description

only_own
boolean
Default: false

If set to true, only the callers own insights will be returned

page
integer >= 1
Default: 1

Result page that you want to retrieve.

perPage
integer [ 1 .. 500 ]
Default: 20

Maximum number of records per page. Can be at most 500

Responses

Request samples 

curl --request GET \
  --url 'https://api.cashbuzz.io/v01/descriptions/insights?section=SOME_STRING_VALUE&group=SOME_STRING_VALUE&only_own=SOME_BOOLEAN_VALUE&page=SOME_INTEGER_VALUE&perPage=SOME_INTEGER_VALUE' \
  --header 'x-api-Key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "insights": [
    ],
  • "paging": {
    }
}