inapi-java-client.0.1.73.source-code.swagger.json Maven / Gradle / Ivy
Show all versions of finapi-java-client Show documentation
{
"swagger": "2.0",
"info": {
"description": "finAPI RESTful Services",
"version": "v1.73.0",
"title": "finAPI RESTful Services"
},
"basePath": "/",
"tags": [
{
"name": "Accounts"
},
{
"name": "Authorization"
},
{
"name": "Bank Connections"
},
{
"name": "Banks"
},
{
"name": "Categories"
},
{
"name": "Client Configuration"
},
{
"name": "Labels"
},
{
"name": "Mandator Administration"
},
{
"name": "Mocks and Tests"
},
{
"name": "Notification Rules"
},
{
"name": "Payments"
},
{
"name": "Securities"
},
{
"name": "Transactions"
},
{
"name": "Users"
},
{
"name": "Web Forms"
}
],
"schemes": [
"https"
],
"paths": {
"/api/v1/accounts": {
"get": {
"tags": [
"Accounts"
],
"summary": "Get and search all accounts",
"description": "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.",
"operationId": "getAndSearchAllAccounts",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "search",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "accountTypeIds",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "bankConnectionIds",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "minLastSuccessfulUpdate",
"in": "query",
"description": "Lower bound for a 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.",
"required": false,
"type": "string"
},
{
"name": "maxLastSuccessfulUpdate",
"in": "query",
"description": "Upper bound for a 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.",
"required": false,
"type": "string"
},
{
"name": "minBalance",
"in": "query",
"description": "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",
"required": false,
"type": "number"
},
{
"name": "maxBalance",
"in": "query",
"description": "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",
"required": false,
"type": "number"
}
],
"responses": {
"200": {
"description": "List of requested accounts",
"schema": {
"$ref": "#/definitions/AccountList"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "3"
}
},
"delete": {
"tags": [
"Accounts"
],
"summary": "Delete all accounts",
"description": "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.
- All notification rules that are connected to any specific accounts will get deleted as well.
- If at least one of the user's bank connections in currently in the process of import, update, or transactions categorization, then this service will perform no action at all.",
"operationId": "deleteAllAccounts",
"responses": {
"200": {
"description": "List of identifiers of deleted accounts",
"schema": {
"$ref": "#/definitions/IdentifierList"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "No action was performed as at least one account is currently being imported, updated (either by the user or by finAPI's automatic batch update), or because the categorization of transactions is performed.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "11"
}
}
},
"/api/v1/accounts/dailyBalances": {
"get": {
"tags": [
"Accounts"
],
"summary": "Get daily balances",
"description": "Returns the user's daily balances for a given period and a set of specified accounts (or all accounts, if none are specified). The daily balances are calculated by finAPI and are based on the current balances of the regarded accounts.",
"operationId": "getDailyBalances",
"parameters": [
{
"name": "accountIds",
"in": "query",
"description": "A comma-separated list of (non-security) account identifiers. If no accounts are specified, all (non-security) accounts of the user are regarded.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "startDate",
"in": "query",
"description": "A string in the format 'YYYY-MM-DD'. Note that the requested date range [startDate..endDate] may not exceed 365 days. If startDate is not specified, it defaults to the endDate minus one month.",
"required": false,
"type": "string"
},
{
"name": "endDate",
"in": "query",
"description": "A string in the format 'YYYY-MM-DD'. Note that the requested date range [startDate..endDate] may not exceed 365 days. If endDate is not specified, it defaults to today's date.",
"required": false,
"type": "string"
},
{
"name": "withProjection",
"in": "query",
"description": "Whether finAPI should project the first and last actually existing balance of an account into the past and future. When passing 'true', then the result will always contain a daily balance for every day of the entire requested date range, even for days before the first actually existing balance, resp. after the last actually existing balance. Those days will have the same balance as the day of the first actual balance, resp. last actual balance, i.e. the first/last balance will be infinitely projected into the past/the future. When passing 'false', then the result will contain daily balances only from the day on where the first actual balance exists for any of the regarded accounts, and only up to the day where the last actual balance exists for any of the regarded accounts. Note that when in this case there are no actual balances within the requested date range, then an empty array will be returned. Default value for this parameter is 'true'.",
"required": false,
"type": "boolean",
"default": true
},
{
"name": "page",
"in": "query",
"description": "Result page that you want to retrieve.",
"required": false,
"type": "integer",
"default": 1,
"minimum": 1.0
},
{
"name": "perPage",
"in": "query",
"description": "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.",
"required": false,
"type": "integer",
"default": 20,
"maximum": 500.0,
"minimum": 1.0
},
{
"name": "order",
"in": "query",
"description": "Determines the order of the results. You can order the results by 'date', 'balance', 'income' or 'spending'. The default order for this service is 'date,asc'. You can also order by multiple properties. In that case the order of the parameters passed is important. Example: '/accounts/dailyBalances?order=date,desc&order=balance,asc' will return daily balances ordered by 'date' (descending), where items with the same 'date' are ordered by 'balance' (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). ",
"required": false,
"type": "array",
"items": {
"type": "string",
"default": "date,ASC"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "List of requested daily balances",
"schema": {
"$ref": "#/definitions/DailyBalanceList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Account(s) not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "Invalid date range (e.g. endDate < startDate)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "4"
}
}
},
"/api/v1/accounts/executeSepaDirectDebit": {
"post": {
"tags": [
"Accounts"
],
"summary": "Execute SEPA Direct Debit",
"description": "Execute a SEPA direct debit order that has been previously submitted by the use of the /requestSepaDirectDebit service.
Note: in case of using finAPI's web form flow, the web form is dealing with triggering this service itself.
Note that this service only works when your client has payments enabled (see client configuration).",
"operationId": "executeSepaDirectDebit",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Parameters for the execution of a SEPA direct debit order",
"required": true,
"schema": {
"$ref": "#/definitions/ExecuteSepaDirectDebitParams"
}
}
],
"responses": {
"200": {
"description": "Response for the SEPA Direct Debit execute",
"schema": {
"$ref": "#/definitions/PaymentExecutionResponse"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role or your client does not have payments enabled (see client configuration)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Account not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ILLEGAL_ENTITY_STATE if no pending SEPA direct debit order exists for the account; BANK_SERVER_REJECTION if the bank server responded with an error message when finAPI tried to execute the direct debit order. The response's error message can be forwarded to the user, it will typically contain a german message from the bank server that contains useful information.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "SEPA Direct Debit cannot get executed at the moment as the update is currently being executed (either by the user or by finAPI's automatic batch update).",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "9"
}
}
},
"/api/v1/accounts/executeSepaMoneyTransfer": {
"post": {
"tags": [
"Accounts"
],
"summary": "Execute SEPA Money Transfer",
"description": "Execute a SEPA money transfer order that has been previously submitted by the use of the /requestSepaMoneyTransfer service.
Note: in case of using finAPI's web form flow, the web form is dealing with triggering this service itself.
Note that this service only works when your client has payments enabled (see client configuration).",
"operationId": "executeSepaMoneyTransfer",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Parameters for the execution of a SEPA money transfer order",
"required": true,
"schema": {
"$ref": "#/definitions/ExecuteSepaMoneyTransferParams"
}
}
],
"responses": {
"200": {
"description": "Response for the SEPA Money Transfer execute",
"schema": {
"$ref": "#/definitions/PaymentExecutionResponse"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role or your client does not have payments enabled (see client configuration)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Account not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ILLEGAL_ENTITY_STATE if no pending SEPA money transfer order exists for the account; BANK_SERVER_REJECTION if the bank server responded with an error message when finAPI tried to execute the money transfer order. The response's error message can be forwarded to the user, it will typically contain a german message from the bank server that contains useful information.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "SEPA Money Transfer cannot get executed at the moment as the update is currently being executed (either by the user or by finAPI's automatic batch update).",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "7"
}
}
},
"/api/v1/accounts/requestSepaDirectDebit": {
"post": {
"tags": [
"Accounts"
],
"summary": "Request SEPA Direct Debit",
"description": "Submit a SEPA direct debit order for one or multiple direct debits. Returns an instruction from the bank server that can be displayed to the user (e.g. \"Enter TAN\"), typically in the language of the bank's country. The order remains valid for execution for only a couple of minutes (the exact validity period depends on the bank). For executing the order, use the /executeSepaDirectDebit service after calling this service. Note that when the order is not executed within the validity period, the bank might take note of that and - if happening too often - ultimately lock the user's online banking access. If there already exists a previously submitted but not yet executed SEPA order for this account (either another direct debit order, or a money transfer order), then that order will be discarded and replaced with the new order that is being created with this service call.
Notes:
• When using a two-step-procedure with flag 'implicitExecute' = true, then this service will immediately execute the direct debit. The response will not contain any challenge message and you won't be required to make a subsequent call to /executeSepaDirectDebit.
NOTE: Depending on your license, this service may respond with HTTP code 451, containing an error message with a 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 finAPI's web form. For a detailed explanation of the Web Form Flow, please refer to this article: finAPI's Web Form Flow
Note that this service only works when your client has payments enabled (see client configuration).",
"operationId": "requestSepaDirectDebit",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Parameters for a SEPA direct debit request",
"required": true,
"schema": {
"$ref": "#/definitions/RequestSepaDirectDebitParams"
}
}
],
"responses": {
"200": {
"description": "Response for the SEPA Direct Debit request",
"schema": {
"$ref": "#/definitions/DirectDebitOrderingResponse"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role or your client does not have payments enabled (see client configuration)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Account not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ILLEGAL_FIELD_VALUE if SEPA purpose code is specified incorrectly;
ILLEGAL_ENTITY_STATE if no PIN has been specified and finAPI has no PIN stored for the account's bank connection or if the account used for the request is DEPRECATED/not found on bank side;
UNSUPPORTED_ORDER if the account does not support the requested order. Check the account's 'supportedOrders' field for available orders;
IBAN_ONLY_DIRECT_DEBIT_NOT_SUPPORTED if the debitor account's BIC is required but was not set (see Bank Connection resource to find out whether the BIC is required or not);
MISSING_TWO_STEP_PROCEDURE if no two-step-procedure was specified in the input parameters of the service call, and there is no default two-step-procedure set in the account's bank connection neither;
INVALID_TWO_STEP_PROCEDURE if the given two-step-procedure does not match any of the procedures that are listed in the account's bank connection;
BANK_SERVER_REJECTION if the bank server responded with an error message when finAPI tried to submit the direct debit order. The response's error message can be forwarded to the user, as it will typically contain a german message from the bank server that contains useful information for the user.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "SEPA Direct Debit cannot get requested at the moment as the update is currently being executed (either by the user or by finAPI's automatic batch update).",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"451": {
"description": "In case the user must enter credentials and/or select a two-step-procedure within finAPI's web form. See: finAPI's Web Form Flow",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"501": {
"description": "The given bank is currently not supported by finAPI",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "8"
}
}
},
"/api/v1/accounts/requestSepaMoneyTransfer": {
"post": {
"tags": [
"Accounts"
],
"summary": "Request SEPA Money Transfer",
"description": "Submit a SEPA money transfer order for either a single or a collective money transfer. Returns an instruction from the bank server that can be displayed to the user (e.g. \"Enter TAN\"), typically in the language of the bank's country. The order remains valid for execution for only a couple of minutes (the exact validity period depends on the bank). For executing the order, use the /executeSepaMoneyTransfer service after calling this service. Note that when the order is not executed within the validity period, the bank might take note of that and - if happening too often - ultimately lock the user's online banking access. If there already exists a previously submitted but not yet executed SEPA order for this account (either another money transfer order, or a direct debit order), then that order will be discarded and replaced with the new order that is being created with this service call.
Notes:
• Some banks may require a multi-step authentication, in which case the service will respond with HTTP code 510 and an error message containing a challenge for the user from the bank. You must display the challenge message to the user, and then retry the service call, passing the user's answer to the bank's challenge in the 'challengeResponse' field.
• When using a two-step-procedure with flag 'implicitExecute' = true, then this service will immediately execute the money transfer. The response will not contain any challenge message and you won't be required to make a subsequent call to /executeSepaMoneyTransfer.
NOTE: Depending on your license, this service may respond with HTTP code 451, containing an error message with a 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 finAPI's web form. For a detailed explanation of the Web Form Flow, please refer to this article: finAPI's Web Form Flow
Note that this service only works when your client has payments enabled (see client configuration).",
"operationId": "requestSepaMoneyTransfer",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Parameters for a SEPA money transfer request",
"required": true,
"schema": {
"$ref": "#/definitions/RequestSepaMoneyTransferParams"
}
}
],
"responses": {
"200": {
"description": "Response for the SEPA Money Transfer request",
"schema": {
"$ref": "#/definitions/MoneyTransferOrderingResponse"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role or your client does not have payments enabled (see client configuration)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Account not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ILLEGAL_ENTITY_STATE if no PIN has been specified and finAPI has no PIN stored for the account's bank connection or if the account used for the request is DEPRECATED/not found on bank side;
UNSUPPORTED_ORDER if the account does not support the requested order. Check the account's 'supportedOrders' field for available orders;
IBAN_ONLY_MONEY_TRANSFER_NOT_SUPPORTED if the recipient account's BIC is required but was not set (see Bank Connection resource to find out whether the BIC is required or not);
COLLECTIVE_MONEY_TRANSFER_NOT_SUPPORTED - DEPRECATED! This code will never be returned. If a collective money transfer request was submitted but the account does not support collective money transfers, then the service will return with the code UNSUPPORTED_ORDER;
MISSING_TWO_STEP_PROCEDURE if no two-step-procedure was specified in the input parameters of the service call, and there is no default two-step-procedure set in the account's bank connection either;
INVALID_TWO_STEP_PROCEDURE if the given two-step-procedure does not match any of the procedures that are listed in the account's bank connection;
BANK_SERVER_REJECTION if the bank server responded with an error message when finAPI tried to submit the money transfer order. The response's error message can be forwarded to the user, as it will typically contain a german message from the bank server that contains useful information for the user;
ILLEGAL_FIELD_VALUE if recipient IBAN/Name or clearing account id is not specified or specified incorrectly; if SEPA purpose code is specified incorrectly",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "SEPA Money Transfer cannot get requested at the moment as the update is currently being executed (either by the user or by finAPI's automatic batch update).",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"451": {
"description": "In case the user must enter credentials and/or select a two-step-procedure within finAPI's web form. See: finAPI's Web Form Flow",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"501": {
"description": "The given bank is currently not supported by finAPI",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"510": {
"description": "In case the bank requires an additional authentication by the user. The error's message will contain instructions for the user. Redo the service call and pass the user's answer to the challenge in the 'challengeResponse' field.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "6"
}
}
},
"/api/v1/accounts/{ids}": {
"get": {
"tags": [
"Accounts"
],
"summary": "Get multiple accounts",
"description": "Get a list of multiple bank accounts of the user that is authorized by the access_token. Must pass the accounts' identifiers and the user's access_token. Accounts whose identifiers do not exist or do not relate to the authorized user will not be contained in the result (If this applies to all of the given identifiers, then the result will be an empty list). WARNING: This service is deprecated and will be removed at some point. If you want to get multiple accounts, please instead use the service 'Get and search all accounts' and pass a comma-separated list of identifiers as a parameter 'ids'.",
"operationId": "getMultipleAccounts",
"parameters": [
{
"name": "ids",
"in": "path",
"description": "Comma-separated list of identifiers of requested accounts",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "csv",
"pattern": "[\\d]+,[\\d,]+"
}
],
"responses": {
"200": {
"description": "List of requested accounts",
"schema": {
"$ref": "#/definitions/AccountList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"deprecated": true,
"x-finapi": {
"order": "2"
}
}
},
"/api/v1/accounts/{id}": {
"get": {
"tags": [
"Accounts"
],
"summary": "Get an account",
"description": "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.",
"operationId": "getAccount",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of requested account",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Requested account",
"schema": {
"$ref": "#/definitions/Account"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Account not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
},
"delete": {
"tags": [
"Accounts"
],
"summary": "Delete an account",
"description": "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!
- All notification rules that are connected to the account will get adjusted so that they no longer have this account listed. Notification rules that are connected to just this account (and no other accounts) will get deleted altogether.",
"operationId": "deleteAccount",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of the account to delete",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Account deleted (empty response body)"
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Account not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "Account cannot get deleted at the moment as it is currently being imported or updated (either by the user or by finAPI's automatic batch update), or because the categorization of transactions is performed.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "10"
}
},
"patch": {
"tags": [
"Accounts"
],
"summary": "Edit an account",
"description": "Change the name and/or the type and/or the 'isNew' 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.",
"operationId": "editAccount",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of the account to edit",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
},
{
"in": "body",
"name": "body",
"description": "New account name and/or type and/or 'isNew' flag",
"required": false,
"schema": {
"$ref": "#/definitions/AccountParams"
}
}
],
"responses": {
"200": {
"description": "Edited account",
"schema": {
"$ref": "#/definitions/Account"
}
},
"400": {
"description": "MISSING_FIELD if neither a name, nor a type, nor the 'isNew' flag were specified; UNKNOWN_ENTITY if the given account type id does not exist",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Account not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "Account cannot get edited at the moment as it is currently being imported or updated (either by the user or by finAPI's automatic batch update).",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "5"
}
}
},
"/api/v1/bankConnections": {
"get": {
"tags": [
"Bank Connections"
],
"summary": "Get all bank connections",
"description": "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.",
"operationId": "getAllBankConnections",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "List of requested bank connections",
"schema": {
"$ref": "#/definitions/BankConnectionList"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "3"
}
},
"delete": {
"tags": [
"Bank Connections"
],
"summary": "Delete all bank connections",
"description": "Delete all bank connections of the user that is authorized by the access_token. Must pass the user's access_token.
Notes:
- All notification rules that are connected to any specific bank connection will get deleted as well.
- 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.",
"operationId": "deleteAllBankConnections",
"responses": {
"200": {
"description": "List of identifiers of deleted bank connections",
"schema": {
"$ref": "#/definitions/IdentifierList"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "No action was performed at the moment as at least one bank connection is being imported, updated (either by the user or by finAPI's automatic batch update), or because the categorization of transactions is currently performed.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "8"
}
}
},
"/api/v1/bankConnections/import": {
"post": {
"tags": [
"Bank Connections"
],
"summary": "Import a new bank connection",
"description": "Imports a new bank connection for a specific user. Must pass the connection credentials 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.
Note that some banks may require a multi-step authentication, in which case the service will respond with HTTP code 510 and an error message containing a challenge for the user from the bank. You must display the challenge message to the user, and then retry the service call, passing the user's answer to the bank's challenge in the 'challengeResponse' field.
You can also import a \"demo connection\" which contains a single bank account with some pre-defined transactions. To import the demo connection, you need to pass the identifier of the \"finAPI Test Bank\". In case of demo connection import, any other fields besides the bank identifier can remain unset. The bankingUserId, bankingCustomerId, bankingPin, and storePin fields will be stored if you pass them, however they will not be regarded when updating the demo connection (in other words: It doesn't matter what credentials you choose for the demo connection). Note however that if you want to import the demo connection multiple times for the same user, you must use a different bankingUserId and/or bankingCustomerId for each of the imports. Also note that the skipPositionsDownload flag is ignored for the demo bank connection, i.e. when importing the demo bank connection, you will always get the transactions for its account. You can enable multi-step authentication for the demo bank connection by setting the bank connection name to \"MSA\".
For a more in-depth understanding of the import 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 451, containing an error message with a 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 finAPI's web form. For a detailed explanation of the Web Form Flow, please refer to this article: finAPI's Web Form Flow",
"operationId": "importBankConnection",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Import bank connection parameters",
"required": true,
"schema": {
"$ref": "#/definitions/ImportBankConnectionParams"
}
}
],
"responses": {
"201": {
"description": "Imported bank connection",
"schema": {
"$ref": "#/definitions/BankConnection"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "UNKNOWN_ENTITY if the specified bank identifier does not exist;
ENTITY_EXISTS if such a bank connection already exists;
ILLEGAL_ENTITY_STATE in case of finAPI supports only web scraping for bank, but web scraping is disabled for client;
ILLEGAL_FIELD_VALUE if you tried to import an online connection, but did not specify any 'bankingUserId' and/or 'bankingPin';
BANK_SERVER_REJECTION if the bank server responded with an error message when finAPI tried to retrieve the user's data. The response's error message can be forwarded to the user, it will typically contain a german message from the bank server that contains useful information (like that the given login credentials were not correct or that the connection is not activated for online banking);
NO_ACCOUNTS_FOR_TYPE_LIST if none of the accounts from bank are matching your given accountTypeIds;
NO_EXISTING_CHALLENGE in case the 'challengeResponse' field was set, but there is no pending challenge for this bank connection;
",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"451": {
"description": "In case the user must enter credentials within finAPI's web form. See: finAPI's Web Form Flow",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"501": {
"description": "This bank is currently not supported by finAPI",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"510": {
"description": "In case the bank requires an additional authentication by the user. The error's message will contain instructions for the user. Redo the service call and pass the user's answer to the challenge in the 'challengeResponse' field.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "4"
}
}
},
"/api/v1/bankConnections/update": {
"post": {
"tags": [
"Bank Connections"
],
"summary": "Update a bank connection",
"description": "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 451, containing an error message with a 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 finAPI's web form. For a detailed explanation of the Web Form Flow, please refer to this article: finAPI's Web Form Flow",
"operationId": "updateBankConnection",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Update bank connection parameters",
"required": true,
"schema": {
"$ref": "#/definitions/UpdateBankConnectionParams"
}
}
],
"responses": {
"200": {
"description": "Bank connection that the update was triggered for",
"schema": {
"$ref": "#/definitions/BankConnection"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Bank connection not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "MISSING_FIELD if the PIN is not specified and there is no PIN stored in finAPI for this connection;
ILLEGAL_FIELD_VALUE if the specified banking PIN contains illegal characters;
ILLEGAL_ENTITY_STATE:
- in case of finAPI supports only web scraping for bank, but web scraping is disabled for client;
- if 'skipPositionsDownload' is set to true, but positions have already been downloaded previously;
BANK_SERVER_REJECTION if the bank server responded with an error message when finAPI tried to retrieve the user's data. The response's error message can be forwarded to the user, it will typically contain a german message from the bank server that contains useful information (like that the given login credentials were not correct or that the connection is not activated for online banking);
NO_EXISTING_CHALLENGE in case the 'challengeResponse' field was set, but there is no pending challenge for this bank connection.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "Bank connection cannot get updated at the moment as it is currently being imported or updated (either by the user or by finAPI's automatic batch update).",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"451": {
"description": "In case the user must enter credentials within finAPI's web form. See: finAPI's Web Form Flow",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"501": {
"description": "This bank is currently not supported by finAPI",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"510": {
"description": "In case the bank requires an additional authentication by the user. The error's message will contain instructions for the user. Redo the service call and pass the user's answer to the challenge in the 'challengeResponse' field.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "5"
}
}
},
"/api/v1/bankConnections/{ids}": {
"get": {
"tags": [
"Bank Connections"
],
"summary": "Get multiple bank connections",
"description": "Get a list of multiple bank connections of the user that is authorized by the access_token. Must pass the connections' identifiers and the user's access_token. Connections whose identifiers do not exist or do not relate to the authorized user will not be contained in the result (If this applies to all of the given identifiers, then the result will be an empty list). WARNING: This service is deprecated and will be removed at some point. If you want to get multiple bank connections, please instead use the service 'Get all bank connections' and pass a comma-separated list of identifiers as a parameter 'ids'.",
"operationId": "getMultipleBankConnections",
"parameters": [
{
"name": "ids",
"in": "path",
"description": "Comma-separated list of identifiers of requested bank connections",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "csv",
"pattern": "[\\d]+,[\\d,]+"
}
],
"responses": {
"200": {
"description": "List of requested bank connections",
"schema": {
"$ref": "#/definitions/BankConnectionList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"deprecated": true,
"x-finapi": {
"order": "2"
}
}
},
"/api/v1/bankConnections/{id}": {
"get": {
"tags": [
"Bank Connections"
],
"summary": "Get a bank connection",
"description": "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.",
"operationId": "getBankConnection",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of requested bank connection",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Requested bank connection",
"schema": {
"$ref": "#/definitions/BankConnection"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Bank connection not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
},
"delete": {
"tags": [
"Bank Connections"
],
"summary": "Delete a bank connection",
"description": "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 connection's identifier and the user's access_token.
Notes:
- All notification rules that are connected to the bank connection will get adjusted so that they no longer have this connection listed. Notification rules that are connected to just this bank connection (and no other connection) will get deleted altogether.
- A bank connection cannot get deleted while it is in the process of import, update, or transactions categorization.",
"operationId": "deleteBankConnection",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of the bank connection to delete",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Bank connection deleted (empty response body)"
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Bank connection not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "Bank connection cannot get deleted at the moment as it is currently being imported or updated (either by the user or by finAPI's automatic batch update), or because the categorization of transactions is currently performed.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "7"
}
},
"patch": {
"tags": [
"Bank Connections"
],
"summary": "Edit a bank connection",
"description": "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 451, containing an error message with a 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 finAPI's web form. For a detailed explanation of the Web Form Flow, please refer to this article: finAPI's Web Form Flow",
"operationId": "editBankConnection",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of the bank connection to change the parameters for",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
},
{
"in": "body",
"name": "body",
"description": "New bank connection parameters",
"required": true,
"schema": {
"$ref": "#/definitions/EditBankConnectionParams"
}
}
],
"responses": {
"200": {
"description": "Edited bank connection",
"schema": {
"$ref": "#/definitions/BankConnection"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Bank connection not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "INVALID_TWO_STEP_PROCEDURE:
if submitted two-step-procedure does not exist for the user. Please use one of the procedures that are listed in the bank connection;
ILLEGAL_FIELD_VALUE:
if the bank connection's credentials were tried to be changed, but the new credentials are equal to the credentials of another existing bank connection of the same bank.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "Bank connection cannot get edited at the moment as it is currently being imported or updated (either by the user or by finAPI's automatic batch update).",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"451": {
"description": "In case the user must enter credentials within finAPI's web form. See: finAPI's Web Form Flow",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "6"
}
}
},
"/api/v1/banks": {
"get": {
"tags": [
"Banks"
],
"summary": "Get and search all banks",
"description": "Get and search banks from finAPI's 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.",
"operationId": "getAndSearchAllBanks",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "search",
"in": "query",
"description": "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 finAPI 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.",
"required": false,
"type": "string"
},
{
"name": "isSupported",
"in": "query",
"description": "If specified, then only supported (in case of 'true' value) or unsupported (in case of 'false' value) banks will be regarded.",
"required": false,
"type": "boolean"
},
{
"name": "pinsAreVolatile",
"in": "query",
"description": "If specified, then only those banks will be regarded that have the given value (true or false) for their 'pinsAreVolatile' field.",
"required": false,
"type": "boolean"
},
{
"name": "supportedDataSources",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "multi"
},
{
"name": "location",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "multi"
},
{
"name": "isTestBank",
"in": "query",
"description": "If specified, then only those banks will be regarded that have the given value (true or false) for their 'isTestBank' field.",
"required": false,
"type": "boolean"
},
{
"name": "page",
"in": "query",
"description": "Result page that you want to retrieve.",
"required": false,
"type": "integer",
"default": 1,
"minimum": 1.0
},
{
"name": "perPage",
"in": "query",
"description": "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.",
"required": false,
"type": "integer",
"default": 20,
"maximum": 500.0,
"minimum": 1.0
},
{
"name": "order",
"in": "query",
"description": "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). ",
"required": false,
"type": "array",
"items": {
"type": "string",
"default": "id,ASC"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "List of requested banks",
"schema": {
"$ref": "#/definitions/PageableBankList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "You are not allowed to call this service",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "3"
}
}
},
"/api/v1/banks/{ids}": {
"get": {
"tags": [
"Banks"
],
"summary": "Get multiple banks",
"description": "Get a list of multiple banks from finAPI's database of banks. You have to pass a list of bank identifiers, and either the authorized user's access_token, or your client's access token. Note that banks whose identifiers do not exist will not be contained in the result (If this applies to all of the given identifiers, then the result will be an empty list).
WARNING: This service is deprecated and will be removed at some point. If you want to get multiple banks, please instead use the service 'Get and search all banks' and pass a comma-separated list of identifiers with the parameter 'ids'.",
"operationId": "getMultipleBanks",
"parameters": [
{
"name": "ids",
"in": "path",
"description": "Comma-separated list of identifiers of requested banks",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "csv",
"pattern": "[\\d]+,[\\d,]+"
}
],
"responses": {
"200": {
"description": "List of requested banks",
"schema": {
"$ref": "#/definitions/BankList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "You are not allowed to call this service",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"deprecated": true,
"x-finapi": {
"order": "2"
}
}
},
"/api/v1/banks/{id}": {
"get": {
"tags": [
"Banks"
],
"summary": "Get a bank",
"description": "Get a single bank from finAPI's 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.",
"operationId": "getBank",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of requested bank",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Requested Bank",
"schema": {
"$ref": "#/definitions/Bank"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "You are not allowed to call this service",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Bank not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
}
},
"/api/v1/categories": {
"get": {
"tags": [
"Categories"
],
"summary": "Get and search all categories",
"description": "Get a list of all global finAPI categories as well as all custom categories of the authorized user. Must pass the user's access_token. You can set optional search criteria to get only those categories that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.",
"operationId": "getAndSearchAllCategories",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "A comma-separated list of category identifiers. If specified, then only categories whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 1000.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "search",
"in": "query",
"description": "If specified, then only those categories will be contained in the result whose 'name' contains the given search string (the matching works case-insensitive). If no categories contain the search string in their name, 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 name in order for a category to get included into the result.",
"required": false,
"type": "string"
},
{
"name": "isCustom",
"in": "query",
"description": "If specified, then the result will contain only categories that are either finAPI global (in case of value 'false'), or only categories that have been created by the authorized user (in case of value 'true').",
"required": false,
"type": "boolean"
},
{
"name": "page",
"in": "query",
"description": "Result page that you want to retrieve.",
"required": false,
"type": "integer",
"default": 1,
"minimum": 1.0
},
{
"name": "perPage",
"in": "query",
"description": "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.",
"required": false,
"type": "integer",
"default": 20,
"maximum": 500.0,
"minimum": 1.0
},
{
"name": "order",
"in": "query",
"description": "Determines the order of the results. You can order the results by 'id', 'name' and 'isCustom'. The default order is 'id,asc'. You can also order by multiple properties. In that case the order of the parameters passed is important. Example: '/categories?order=isCustom,desc&order=name' will return all custom categories followed by all default categories. Both groups are ordered ascending by name. 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). ",
"required": false,
"type": "array",
"items": {
"type": "string",
"default": "id,ASC"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "List of requested categories",
"schema": {
"$ref": "#/definitions/PageableCategoryList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "3"
}
},
"post": {
"tags": [
"Categories"
],
"summary": "Create a new category",
"description": "Create a new custom transaction category for the authorized user, that can then be assigned to transactions via PATCH /transactions, and that will also be regarded in finAPI's automatic transactions categorization process. Must pass the user's access_token.",
"operationId": "createCategory",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Parameters of the new category",
"required": false,
"schema": {
"$ref": "#/definitions/CategoryParams"
}
}
],
"responses": {
"201": {
"description": "Created category",
"schema": {
"$ref": "#/definitions/Category"
}
},
"400": {
"description": "The category name is too long. The maximum length for a category name is 128.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "UNKNOWN_ENTITY if the parent category does not exist.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ILLEGAL_ENTITY_STATE if The given parentId references a sub-category instead of a main category (Multi-level sub-categories are not supported);
ENTITY_EXISTS if a category with that name already exists.
NOTE: A category already exists means that there is another category of the same name on the same hierarchy level.
Examples:
• if you want to add a sub-category 'Sub' to the main category 'Main', and 'Main' already contains 'Sub', then the category already exists and cannot get created.
• if you want to add a sub-category 'Sub' to the main category 'Main', and some other main category contains 'Sub' (or a main category itself is called 'Sub'), then the category can still get created, because there is no 'Sub' in the 'Main' category
• if you want to add a new main-category 'Main' and there is already a main category with that name, then the category already exists and cannot get created",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "5"
}
},
"delete": {
"tags": [
"Categories"
],
"summary": "Delete all categories",
"description": "Delete all custom categories of the user that is authorized by the access_token. Must pass the user's access_token. Note that this deletes both parent categories as well as any related sub-categories.",
"operationId": "deleteAllCategories",
"responses": {
"200": {
"description": "List of identifiers of deleted categories",
"schema": {
"$ref": "#/definitions/IdentifierList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "9"
}
}
},
"/api/v1/categories/cashFlows": {
"get": {
"tags": [
"Categories"
],
"summary": "Get cash flows",
"description": "Get the cash flow(s) (= total income, spending, and balance) for one or several categories. You can specify various criteria such as the time period to calculate the cash flows for, or what categories to do the calculations for. Note that the cash flow for a category may include the cash flows for all of its sub-categories, or not include it, depending on the 'includeSubCashFlows' setting. Must pass the user's access_token.",
"operationId": "getCashFlows",
"parameters": [
{
"name": "search",
"in": "query",
"description": "If specified, then only transactions that contain the search term in their purpose or counterpart fields will be contained in the result. Note that the search is case insensitive.",
"required": false,
"type": "string"
},
{
"name": "counterpart",
"in": "query",
"description": "The counterpart is the person or institution that received your payment, or that you made the payment to. If this parameter is specified, then only transactions that contain the given term in one (or more) of their counterpart fields ('counterpartName', 'counterpartAccountNumber', 'counterpartIban', 'counterpartBic' or 'counterpartBlz') will be contained in the result. Note that the search is case insensitive.",
"required": false,
"type": "string"
},
{
"name": "purpose",
"in": "query",
"description": "If specified, then only those transactions will be contained in the result whose purpose field contains the given search string. Note that the search is case insensitive.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.",
"required": false,
"type": "string"
},
{
"name": "accountIds",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "minBankBookingDate",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "maxBankBookingDate",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "minFinapiBookingDate",
"in": "query",
"description": "Lower bound for a transaction's booking date as set by finAPI, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). For details about the meaning of the finAPI booking date, please see the field's documentation in the service's response.",
"required": false,
"type": "string"
},
{
"name": "maxFinapiBookingDate",
"in": "query",
"description": "Upper bound for a transaction's booking date as set by finAPI, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). For details about the meaning of the finAPI booking date, please see the field's documentation in the service's response.",
"required": false,
"type": "string"
},
{
"name": "minAmount",
"in": "query",
"description": "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",
"required": false,
"type": "number"
},
{
"name": "maxAmount",
"in": "query",
"description": "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",
"required": false,
"type": "number"
},
{
"name": "direction",
"in": "query",
"description": "If specified, then only transactions with the given direction(s) will be regarded. Use 'income' for regarding only received payments (amount >= 0), 'spending' for regarding only outgoing payments (amount < 0), or 'all' to regard both directions. If not specified, the direction defaults to 'all'.",
"required": false,
"type": "string",
"default": "all",
"enum": [
"all",
"income",
"spending"
]
},
{
"name": "labelIds",
"in": "query",
"description": "A comma-separated list of label identifiers. If specified, then only transactions that have been marked with at least one of the given labels will be contained in the result.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "categoryIds",
"in": "query",
"description": "If specified, then the result will contain only those cash flows that relate to the given categories. Note that the cash flow for a category may include/exclude the cash flows of its sub-categories, depending on the 'includeSubCashFlows' setting. To include the cash flow of not categorized transactions, pass the value '0' as categoryId. Note: When this parameter is NOT set, then the result will contain a cash flow for all categories that have transactions associated to them (this includes the 'null'-category for the cash flow of not categorized transactions), more precisely: transactions that fulfill the filter criteria. Categories that have no associated transactions according to the filter criteria will not appear in the result. However, when you specify this parameter, then all specified categories will have a cash flow entry in the result, even if there are no associated transactions for the category (the cash flow will have income, spending and balance all set to zero).",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "isNew",
"in": "query",
"description": "If specified, then only transactions that have their 'isNew' flag set to true/false will be regarded for the cash flow calculations.",
"required": false,
"type": "boolean"
},
{
"name": "minImportDate",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "maxImportDate",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "includeSubCashFlows",
"in": "query",
"description": "If it is true, then the income, spending, balance and count of transactions of a main category results from all transactions that have either this (main) category or any of its subcategories assigned (of course all transactions depends from the other filtering settings); If it is false, then the income, spending, balance and count of transactions of a main category only results from the transactions that have exactly this (main) category assigned. Default value for this parameter is 'true'.",
"required": false,
"type": "boolean",
"default": true
},
{
"name": "order",
"in": "query",
"description": "Determines the order of the results. You can order the results by 'income', 'spending', 'balance', 'category.id' or 'category.name'. The default order for this service is 'category.id,asc'. You can also order by multiple properties. In that case the order of the parameters passed is important. Example: '/cashFlows?order=income,desc&order=spending,asc&balance,desc' will return as first result the category with the highest income. If two categories have the same income, it returns the category with the highest spending first (because spending is a negative value) and so on. 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). ",
"required": false,
"type": "array",
"items": {
"type": "string",
"default": "category.id,ASC"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "List of requested cash flows",
"schema": {
"$ref": "#/definitions/CashFlowList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Category not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "4"
}
}
},
"/api/v1/categories/trainCategorization": {
"post": {
"tags": [
"Categories"
],
"summary": "Train categorization",
"description": "This service allows you to create user-specific categorization rules (for the user that is authorized by the access_token). Pass a categorization sample (=set of transaction data and a target category), and finAPI will train the user's categorization rules so that similar transactions will be categorized accordingly in future. Basically, this service behaves the same as when assigning categories to existing transactions via the 'Edit a transaction' service, with the difference that you can directly pass transaction data to this service, without the need of having any transactions actually imported in finAPI. Must pass the user's access_token.",
"operationId": "trainCategorization",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Categorization sample",
"required": false,
"schema": {
"$ref": "#/definitions/TrainCategorizationData"
}
}
],
"responses": {
"200": {
"description": "Categorization rules updated (empty response body)"
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Category not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "The number of transactions exceeds the limit of 100.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "6"
}
}
},
"/api/v1/categories/{ids}": {
"get": {
"tags": [
"Categories"
],
"summary": "Get multiple categories",
"description": "Get a list of multiple categories that are either a global finAPI category or a custom category of the authorized user. Must pass the categories' identifiers and the user's access_token. Categories whose identifiers do not exist or that relate to a different user not be contained in the result (If this applies to all of the given identifiers, then the result will be an empty list). WARNING: This service is deprecated and will be removed at some point. If you want to get multiple categories, please instead use the service 'Get and search all categories' and pass a comma-separated list of identifiers as a parameter 'ids'.",
"operationId": "getMultipleCategories",
"parameters": [
{
"name": "ids",
"in": "path",
"description": "Comma-separated list of identifiers of requested categories",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "csv",
"pattern": "[\\d]+,[\\d,]+"
}
],
"responses": {
"200": {
"description": "List of requested categories",
"schema": {
"$ref": "#/definitions/CategoryList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"deprecated": true,
"x-finapi": {
"order": "2"
}
}
},
"/api/v1/categories/{id}": {
"get": {
"tags": [
"Categories"
],
"summary": "Get a category",
"description": "Get a single category that is either a global finAPI category or a custom category of the authorized user. Must pass the category's identifier and the user's access_token.",
"operationId": "getCategory",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Category identifier",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Requested category",
"schema": {
"$ref": "#/definitions/Category"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Category not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
},
"delete": {
"tags": [
"Categories"
],
"summary": "Delete a category",
"description": "Delete a single category of the user that is authorized by the access_token. Must pass the user's access_token. Note that you can only delete user-custom categories (category's where the 'isCustom' flag is true). Also note that when deleting a parent category, all its sub-categories will be deleted as well.",
"operationId": "deleteCategory",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Category identifier",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Category was deleted successfully (empty response body)"
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Category not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "Category cannot be deleted",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "8"
}
},
"patch": {
"tags": [
"Categories"
],
"summary": "Edit a category",
"description": "Change the name of a custom transaction category belonging to the authorized user. Must pass the user's access_token.",
"operationId": "editCategory",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of the category to edit",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
},
{
"in": "body",
"name": "body",
"description": "New category name",
"required": false,
"schema": {
"$ref": "#/definitions/EditCategoryParams"
}
}
],
"responses": {
"200": {
"description": "Edited transaction category",
"schema": {
"$ref": "#/definitions/Category"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Category not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "Category cannot be edited",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "7"
}
}
},
"/api/v1/clientConfiguration": {
"get": {
"tags": [
"Client Configuration"
],
"summary": "Get client configuration",
"description": "Get your client's configuration. Must pass your global (i.e. client) access_token.",
"operationId": "getClientConfiguration",
"responses": {
"200": {
"description": "Current client configuration",
"schema": {
"$ref": "#/definitions/ClientConfiguration"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
},
"patch": {
"tags": [
"Client Configuration"
],
"summary": "Edit client configuration",
"description": "Edit your client's configuration. Must pass your global (i.e. client) access_token.
NOTE: When token validity periods are changed, this only applies to newly requested tokens, and does not change the expiration time of already existing tokens.",
"operationId": "editClientConfiguration",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Client configuration parameters",
"required": false,
"schema": {
"$ref": "#/definitions/ClientConfigurationParams"
}
}
],
"responses": {
"200": {
"description": "New client configuration",
"schema": {
"$ref": "#/definitions/ClientConfiguration"
}
},
"400": {
"description": "Bad request (e.g. invalid callback URL)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "2"
}
}
},
"/api/v1/labels": {
"get": {
"tags": [
"Labels"
],
"summary": "Get and search all labels",
"description": "Get labels 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 labels that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.",
"operationId": "getAndSearchAllLabels",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "A comma-separated list of label identifiers. If specified, then only labels whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 1000.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "search",
"in": "query",
"description": "If specified, then only those labels will be contained in the result whose 'name' contains the given search string (the matching works case-insensitive). If no labels contain the search string in their name, 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 name in order for a label to get included into the result.",
"required": false,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "Result page that you want to retrieve",
"required": false,
"type": "integer",
"default": 1,
"minimum": 1.0
},
{
"name": "perPage",
"in": "query",
"description": "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.",
"required": false,
"type": "integer",
"default": 20,
"maximum": 500.0,
"minimum": 1.0
},
{
"name": "order",
"in": "query",
"description": "Determines the order of the results. You can order the results by 'id' or 'name'. The default order for all services is 'id,asc'. Since both fields (id and name) are unique, ordering by multiple fields is pointless. The general format is: 'property[,asc|desc]', with 'asc' being the default value. ",
"required": false,
"type": "array",
"items": {
"type": "string",
"default": "id,ASC"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "List of requested labels",
"schema": {
"$ref": "#/definitions/PageableLabelList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "3"
}
},
"post": {
"tags": [
"Labels"
],
"summary": "Create a new label",
"description": "Create a new label for a specific user. Must pass the new label's name and the user's access_token.
Users can create labels to flag transactions (see method PATCH /transactions), with the goal of collecting and getting an overview of all transactions of a certain 'type'. In this sense, labels are similar to transaction categories. However, labels are supposed to depict more of an implicit meaning of a transaction. For instance, a user might want to assign a flag to a transaction that reminds him that he can offset it against tax. At the same time, the category of the transactions might be something like 'insurance', which is a more 'fact-based', or 'objective' way of typing the transaction. Despite this semantic difference between categories and labels, there is also the difference that a transaction can be assigned multiple labels at the same time (while in contrast it can have just a single category).",
"operationId": "createLabel",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Label's name",
"required": true,
"schema": {
"$ref": "#/definitions/LabelParams"
}
}
],
"responses": {
"201": {
"description": "Created label",
"schema": {
"$ref": "#/definitions/Label"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ILLEGAL_FIELD_VALUE if the given label name is too long; ENTITY_EXISTS if a label with the given name already exists",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "4"
}
},
"delete": {
"tags": [
"Labels"
],
"summary": "Delete all labels",
"description": "Delete all labels of the user that is authorized by the access_token. Must pass the user's access_token.",
"operationId": "deleteAllLabels",
"responses": {
"200": {
"description": "List of identifiers of deleted labels",
"schema": {
"$ref": "#/definitions/IdentifierList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "7"
}
}
},
"/api/v1/labels/{ids}": {
"get": {
"tags": [
"Labels"
],
"summary": "Get multiple labels",
"description": "Get a list of multiple labels of the user that is authorized by the access_token.Must pass the labels' identifiers and the user's access_token. Identifiers that do not exist or do not relate to the authorized user will not be contained in the result (If this applies to all of the given identifiers, then the result will be an empty list). WARNING: This service is deprecated and will be removed at some point. If you want to get multiple labels, please instead use the service 'Get all labels' and pass a comma-separated list of identifiers as a parameter 'ids'.",
"operationId": "getMultipleLabels",
"parameters": [
{
"name": "ids",
"in": "path",
"description": "Comma-separated list of identifiers of requested labels",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "csv",
"pattern": "[\\d]+,[\\d,]+"
}
],
"responses": {
"200": {
"description": "List of requested labels",
"schema": {
"$ref": "#/definitions/LabelList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"deprecated": true,
"x-finapi": {
"order": "2"
}
}
},
"/api/v1/labels/{id}": {
"get": {
"tags": [
"Labels"
],
"summary": "Get a label",
"description": "Get a single label of the user that is authorized by the access_token. Must pass the label's identifier and the user's access_token.",
"operationId": "getLabel",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of requested label",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Requested label",
"schema": {
"$ref": "#/definitions/Label"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Label not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
},
"delete": {
"tags": [
"Labels"
],
"summary": "Delete a label",
"description": "Delete a single label of the user that is authorized by the access_token. Must pass the label's identifier and the user's access_token.",
"operationId": "deleteLabel",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of the label to delete",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Label deleted (empty response body)"
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Label not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "6"
}
},
"patch": {
"tags": [
"Labels"
],
"summary": "Edit a label",
"description": "Change the name of a label of the user that is authorized by the access_token. Must pass the label's identifier, the label's new name and the user's access_token.",
"operationId": "editLabel",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Label's identifier",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
},
{
"in": "body",
"name": "body",
"description": "Label's new name",
"required": true,
"schema": {
"$ref": "#/definitions/LabelParams"
}
}
],
"responses": {
"200": {
"description": "Edited label",
"schema": {
"$ref": "#/definitions/Label"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Label not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ILLEGAL_FIELD_VALUE if the given label name is too long; ENTITY_EXISTS if a label with the given name already exists",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "5"
}
}
},
"/api/v1/mandatorAdmin/changeClientCredentials": {
"post": {
"tags": [
"Mandator Administration"
],
"summary": "Change client credentials",
"description": "Change the client_secret for any of your clients, including the mandator admin client. Must pass the mandator admin client's access_token.
NOTES:
• When you change a client's secret, then all of its existing access tokens will be revoked. User access tokens are not affected.
• finAPI is storing client secrets with a one-way encryption. A lost client secret can NOT be recovered.",
"operationId": "changeClientCredentials",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Parameters for changing client credentials",
"required": true,
"schema": {
"$ref": "#/definitions/ChangeClientCredentialsParams"
}
}
],
"responses": {
"200": {
"description": "Client secret successfully changed (empty response body)"
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role. Make sure you're authorized as the mandator admin client.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "The given 'clientId' is unknown or the given 'oldClientSecret' is incorrect",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "3"
}
}
},
"/api/v1/mandatorAdmin/deleteUsers": {
"post": {
"tags": [
"Mandator Administration"
],
"summary": "Delete users",
"description": "Delete one or several users, which are specified by a given list of identifiers. Must pass the mandator admin client's access_token.
NOTE: finAPI may fail to delete one (or several, or all) of the specified users. A user cannot get deleted when his data is currently locked by an internal process (for instance, update of a bank connection or transactions categorization). The response contains the identifiers of all users that could not get deleted, and all users that could get deleted, separated in two lists. The mandator admin client can retry the request at a later time for the users who could not get deleted.
Note that non-existing user identifiers will be ignored entirely, meaning that those identifiers will not appear in the response at all.",
"operationId": "deleteUsers",
"parameters": [
{
"in": "body",
"name": "body",
"description": "List of user identifiers",
"required": true,
"schema": {
"$ref": "#/definitions/UserIdentifiersParams"
}
}
],
"responses": {
"200": {
"description": "List of identifiers of deleted and not deleted users",
"schema": {
"$ref": "#/definitions/UserIdentifiersList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role. Make sure you're authorized as the mandator admin client.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "2"
}
}
},
"/api/v1/mandatorAdmin/getUserList": {
"get": {
"tags": [
"Mandator Administration"
],
"summary": "Get user list",
"description": "Get a list of the users of the mandator that is authorized by the access_token. Must pass the mandator admin client's access_token. You can set optional search criteria to get only those users that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.
Note that the original user id is no longer available in finAPI once a user has been deleted. Because of this, the userId of deleted users will be a distorted version of the original userId. For example, if the deleted user's id was originally 'user', then this service will return 'uXXr' as the userId.
",
"operationId": "getUserList",
"parameters": [
{
"name": "minRegistrationDate",
"in": "query",
"description": "Lower bound for a user's registration date, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only users whose 'registrationDate' is equal to or later than the given date will be regarded.",
"required": false,
"type": "string"
},
{
"name": "maxRegistrationDate",
"in": "query",
"description": "Upper bound for a user's registration date, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only users whose 'registrationDate' is equal to or earlier than the given date will be regarded.",
"required": false,
"type": "string"
},
{
"name": "minDeletionDate",
"in": "query",
"description": "Lower bound for a user's deletion date, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only users whose 'deletionDate' is not null, and is equal to or later than the given date will be regarded.",
"required": false,
"type": "string"
},
{
"name": "maxDeletionDate",
"in": "query",
"description": "Upper bound for a user's deletion date, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only users whose 'deletionDate' is null, or is equal to or earlier than the given date will be regarded.",
"required": false,
"type": "string"
},
{
"name": "minLastActiveDate",
"in": "query",
"description": "Lower bound for a user's last active date, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only users whose 'lastActiveDate' is not null, and is equal to or later than the given date will be regarded.",
"required": false,
"type": "string"
},
{
"name": "maxLastActiveDate",
"in": "query",
"description": "Upper bound for a user's last active date, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). If specified, then only users whose 'lastActiveDate' is null, or is equal to or earlier than the given date will be regarded.",
"required": false,
"type": "string"
},
{
"name": "includeMonthlyStats",
"in": "query",
"description": "Whether to include the 'monthlyStats' for the returned users. If not specified, then the field defaults to 'false'.",
"required": false,
"type": "boolean",
"default": false
},
{
"name": "monthlyStatsStartDate",
"in": "query",
"description": "Minimum bound for the monthly stats (=oldest month that should be included). Must be passed in the format 'YYYY-MM'. If not specified, then the monthly stats will go back up to the first month in which the user existed (date of the user's registration). Note that this field is only regarded if 'includeMonthlyStats' = true.",
"required": false,
"type": "string"
},
{
"name": "monthlyStatsEndDate",
"in": "query",
"description": "Maximum bound for the monthly stats (=latest month that should be included). Must be passed in the format 'YYYY-MM'. If not specified, then the monthly stats will go up to either the current month (for active users), or up to the month of deletion (for deleted users). Note that this field is only regarded if 'includeMonthlyStats' = true.",
"required": false,
"type": "string"
},
{
"name": "minBankConnectionCountInMonthlyStats",
"in": "query",
"description": "A value of X means that the service will return only those users which had at least X bank connections imported at any time within the returned monthly stats set. This field is only regarded when 'includeMonthlyStats' is set to 'true'. The default value for this field is 0.",
"required": false,
"type": "integer",
"default": 0,
"format": "int32"
},
{
"name": "isDeleted",
"in": "query",
"description": "If NOT specified, then the service will regard both active and deleted users in the search. If set to 'true', then ONLY deleted users will be regarded. If set to 'false', then ONLY active users will be regarded.",
"required": false,
"type": "boolean"
},
{
"name": "isLocked",
"in": "query",
"description": "If NOT specified, then the service will regard both locked and not locked users in the search. If set to 'true', then ONLY locked users will be regarded. If set to 'false', then ONLY not locked users will be regarded.",
"required": false,
"type": "boolean"
},
{
"name": "page",
"in": "query",
"description": "Result page that you want to retrieve",
"required": false,
"type": "integer",
"default": 1,
"minimum": 1.0
},
{
"name": "perPage",
"in": "query",
"description": "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.",
"required": false,
"type": "integer",
"default": 20,
"maximum": 500.0,
"minimum": 1.0
},
{
"name": "order",
"in": "query",
"description": "Determines the order of the results. You can order the results by 'userId'. The default order for this service is 'userId,asc'. The general format is: 'property[,asc|desc]', with 'asc' being the default value. ",
"required": false,
"type": "array",
"items": {
"type": "string",
"default": "userId,ASC"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "Requested users list",
"schema": {
"$ref": "#/definitions/PageableUserInfoList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role. Make sure you're authorized as the mandator admin client.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
}
},
"/api/v1/mandatorAdmin/ibanRules": {
"get": {
"tags": [
"Mandator Administration"
],
"summary": "Get IBAN rules",
"description": "Returns all IBAN-based categorization rules that you have defined for your users via the 'Create IBAN rules' service.",
"operationId": "getIbanRuleList",
"parameters": [
{
"name": "page",
"in": "query",
"description": "Result page that you want to retrieve",
"required": false,
"type": "integer",
"default": 1,
"minimum": 1.0
},
{
"name": "perPage",
"in": "query",
"description": "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.",
"required": false,
"type": "integer",
"default": 20,
"maximum": 500.0,
"minimum": 1.0
}
],
"responses": {
"200": {
"description": "Requested IBAN rules",
"schema": {
"$ref": "#/definitions/PageableIbanRuleList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role. Make sure you're authorized as the mandator admin client.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "7"
}
},
"post": {
"tags": [
"Mandator Administration"
],
"summary": "Create IBAN rules",
"description": "This service can be used to define IBAN rules for finAPI's transaction categorization system. The transaction categorization is run automatically whenever new transactions are imported, as well as when you call the services 'Check categorization' or 'Trigger categorization'.
An IBAN rule maps an IBAN to a certain category. finAPI's categorization system will pick the category as a candidate for any transaction whose counterpart's account matches the IBAN. It is not guaranteed though that this candidate will actually be applied, as there could be other categorization rules that have higher priority or that are an even better match for the transaction.
Note that the rules that you define here will be applied to all of your users. They have higher priority than finAPI's default categorization rules, but lower priority than user-specific rules (User-specific rules are created implicitly whenever a category is manually assigned to a transaction via the PATCH /transactions services). IBAN rules have a higher priority than keyword rules (see the 'Create keyword rules' service).",
"operationId": "createIbanRules",
"parameters": [
{
"in": "body",
"name": "body",
"description": "IBAN rule definitions",
"required": true,
"schema": {
"$ref": "#/definitions/IbanRulesParams"
}
}
],
"responses": {
"201": {
"description": "Created IBAN rules",
"schema": {
"$ref": "#/definitions/IbanRuleList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Category not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ENTITY_EXISTS if at least one of the given rules already exists",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "8"
}
}
},
"/api/v1/mandatorAdmin/ibanRules/delete": {
"post": {
"tags": [
"Mandator Administration"
],
"summary": "Delete IBAN rules",
"description": "Delete one or multiple IBAN rules that you have previously created via the 'Create IBAN rules' service.",
"operationId": "deleteIbanRules",
"parameters": [
{
"in": "body",
"name": "body",
"description": "List of IBAN rules identifiers.The maximum number of identifiers is 100.",
"required": true,
"schema": {
"$ref": "#/definitions/IdentifiersParams"
}
}
],
"responses": {
"200": {
"description": "List of identifiers of deleted IBAN rules",
"schema": {
"$ref": "#/definitions/IdentifierList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role. Make sure you're authorized as the mandator admin client.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "IBAN rule not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "9"
}
}
},
"/api/v1/mandatorAdmin/keywordRules": {
"get": {
"tags": [
"Mandator Administration"
],
"summary": "Get keyword rules",
"description": "Returns all keyword-based categorization rules that you have defined for your users via the 'Create keyword rules' service.",
"operationId": "getKeywordRuleList",
"parameters": [
{
"name": "page",
"in": "query",
"description": "Result page that you want to retrieve",
"required": false,
"type": "integer",
"default": 1,
"minimum": 1.0
},
{
"name": "perPage",
"in": "query",
"description": "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.",
"required": false,
"type": "integer",
"default": 20,
"maximum": 500.0,
"minimum": 1.0
}
],
"responses": {
"200": {
"description": "Requested keyword rules",
"schema": {
"$ref": "#/definitions/PageableKeywordRuleList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role. Make sure you're authorized as the mandator admin client.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "4"
}
},
"post": {
"tags": [
"Mandator Administration"
],
"summary": "Create keyword rules",
"description": "This service can be used to define keyword rules for finAPI's transaction categorization system. The transaction categorization is run automatically whenever new transactions are imported, as well as when you call the services 'Check categorization' or 'Trigger categorization'.
A keyword rule maps a set of keywords to a certain category. finAPI's categorization system will pick the category as a candidate for any transaction that contains at least one of the defined keywords in its purpose or counterpart information. It is not guaranteed though that this candidate will actually be applied, as there could be other categorization rules that have higher priority or that are an even better match for the transaction. If there are multiple keyword rules that match a transaction, finAPI will pick the one with the highest count of matched keywords.
Note that the rules that you define here will be applied to all of your users. They have higher priority than finAPI's default categorization rules, but lower priority than user-specific rules (User-specific rules are created implicitly whenever a category is manually assigned to a transaction via the PATCH /transactions services). Keyword rules have a lower priority than IBAN rules (see the 'Create IBAN rules' service).",
"operationId": "createKeywordRules",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Keyword rule definitions",
"required": true,
"schema": {
"$ref": "#/definitions/KeywordRulesParams"
}
}
],
"responses": {
"201": {
"description": "Created keyword rules",
"schema": {
"$ref": "#/definitions/KeywordRuleList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Category not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ENTITY_EXISTS if at least one of the given rules already exists; ILLEGAL_FIELD_VALUE if the request contains incorrect keywords.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "5"
}
}
},
"/api/v1/mandatorAdmin/keywordRules/delete": {
"post": {
"tags": [
"Mandator Administration"
],
"summary": "Delete keyword rules",
"description": "Delete one or multiple keyword rules that you have previously created via the 'Create keyword rules' service.",
"operationId": "deleteKeywordRules",
"parameters": [
{
"in": "body",
"name": "body",
"description": "List of keyword rule identifiers.The maximum number of identifiers is 100.",
"required": true,
"schema": {
"$ref": "#/definitions/IdentifiersParams"
}
}
],
"responses": {
"200": {
"description": "List of identifiers of deleted keyword rules",
"schema": {
"$ref": "#/definitions/IdentifierList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role. Make sure you're authorized as the mandator admin client.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Keyword rule not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "6"
}
}
},
"/api/v1/notificationRules": {
"get": {
"tags": [
"Notification Rules"
],
"summary": "Get and search all notification rules",
"description": "Get notification rules 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 notification rules that you are interested in. If you do not specify any search criteria, then this service functions as a 'get all' service.",
"operationId": "getAndSearchAllNotificationRules",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "A comma-separated list of notification rule identifiers. If specified, then only notification rules whose identifier match any of the given identifiers will be regarded. The maximum number of identifiers is 1000.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "triggerEvent",
"in": "query",
"description": "If specified, then only notification rules with given trigger event will be regarded.",
"required": false,
"type": "string",
"enum": [
"NEW_ACCOUNT_BALANCE",
"NEW_TRANSACTIONS",
"BANK_LOGIN_ERROR",
"FOREIGN_MONEY_TRANSFER",
"LOW_ACCOUNT_BALANCE",
"HIGH_TRANSACTION_AMOUNT",
"CATEGORY_CASH_FLOW",
"NEW_TERMS_AND_CONDITIONS"
]
},
{
"name": "includeDetails",
"in": "query",
"description": "If specified, then only notification rules that include or not include details will be regarded.",
"required": false,
"type": "boolean"
}
],
"responses": {
"200": {
"description": "List of requested notification rules",
"schema": {
"$ref": "#/definitions/NotificationRuleList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "You are not allowed to call this service",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "2"
}
},
"post": {
"tags": [
"Notification Rules"
],
"summary": "Create a new notification rule",
"description": "Create a new notification rule for a specific user. Must pass the user's access_token.
Setting up notification rules for a user allows your client application to get notified about changes in the user's data, e.g. when new transactions were downloaded, an account's balance has changed, or the user's banking credentials are no longer correct. Note that currently, this feature is implemented only for finAPI's automatic batch update, i.e. notification rules are only relevant when the user has activated the automatic updates (and when the automatic batch update is activated in general for your client).
There are different kinds of notification rules. The kind of a rule is depicted by the 'triggerEvent'. The trigger event specifies what data you have to pass when creating a rule (specifically, the contents of the 'params' field), on which events finAPI will send notifications to your client application, as well as what data is contained in those notifications. The specifics of the different trigger events are documented in the following article on our Dev Portal: How to create notification rules and receive notifications",
"operationId": "createNotificationRule",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Notification rule parameters",
"required": true,
"schema": {
"$ref": "#/definitions/NotificationRuleParams"
}
}
],
"responses": {
"201": {
"description": "Created notification rule",
"schema": {
"$ref": "#/definitions/NotificationRule"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "You are not allowed to call this service",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ILLEGAL_FIELD_VALUE if the given 'triggerEvent' does not match any of the known constants, or if the 'params' field contains illegal parameters for the respective trigger event; ENTITY_EXISTS if such a notification rule already exists",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "Notification rules cannot get created at the moment as finAPI's automatic batch update is currently being executed",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "3"
}
},
"delete": {
"tags": [
"Notification Rules"
],
"summary": "Delete all notification rules",
"description": "Delete all notification rules of the user that is authorized by the access_token. Must pass the user's access_token. ",
"operationId": "deleteAllNotificationRules",
"responses": {
"200": {
"description": "List of identifiers of deleted notification rules",
"schema": {
"$ref": "#/definitions/IdentifierList"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "You are not allowed to call this service",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "Notification rules cannot get deleted at the moment as finAPI's automatic batch update is currently being executed",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "5"
}
}
},
"/api/v1/notificationRules/{id}": {
"get": {
"tags": [
"Notification Rules"
],
"summary": "Get a notification rule",
"description": "Get a single notification rule of the user that is authorized by the access_token. Must pass the notification rule's identifier and the user's access_token.",
"operationId": "getNotificationRule",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of requested notification rule",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Requested notification rule",
"schema": {
"$ref": "#/definitions/NotificationRule"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "You are not allowed to call this service",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Notification rule not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
},
"delete": {
"tags": [
"Notification Rules"
],
"summary": "Delete a notification rule",
"description": "Delete a single notification rule of the user that is authorized by the access_token. Must pass the notification rule's identifier and the user's access_token.",
"operationId": "deleteNotificationRule",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of the notification rule to delete",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Notification rule deleted (empty response body)"
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "You are not allowed to call this service",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Notification rule not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "Notification rules cannot get deleted at the moment as finAPI's automatic batch update is currently being executed",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "4"
}
}
},
"/api/v1/payments": {
"get": {
"tags": [
"Payments"
],
"summary": "Get payments",
"description": "Get payments of the user that is authorized by the access_token. Note: For requesting / executing payments, please refer to the 'Accounts' section of the API.
",
"operationId": "getPayments",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "A comma-separated list of payment identifiers. If specified, then only payments whose identifier is matching any of the given identifiers will be regarded. The maximum number of identifiers is 1000.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "accountIds",
"in": "query",
"description": "A comma-separated list of account identifiers. If specified, then only payments that relate to the given account(s) will be regarded. The maximum number of identifiers is 1000.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "minAmount",
"in": "query",
"description": "If specified, then only those payments are regarded whose (absolute) total amount is equal or greater than the given amount will be regarded. The value must be a positive (absolute) amount.",
"required": false,
"type": "number"
},
{
"name": "maxAmount",
"in": "query",
"description": "If specified, then only those payments are regarded whose (absolute) total amount is equal or less than the given amount will be regarded. Value must be a positive (absolute) amount.",
"required": false,
"type": "number"
},
{
"name": "page",
"in": "query",
"description": "Result page that you want to retrieve",
"required": false,
"type": "integer",
"default": 1,
"minimum": 1.0
},
{
"name": "perPage",
"in": "query",
"description": "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.",
"required": false,
"type": "integer",
"default": 20,
"maximum": 500.0,
"minimum": 1.0
},
{
"name": "order",
"in": "query",
"description": "Determines the order of the results. You can use the following fields for ordering the response: 'id', 'amount', 'requestDate' and 'executionDate'. The default order for all services is 'id,asc'.",
"required": false,
"type": "array",
"items": {
"type": "string",
"default": "id,ASC"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "List of requested payments",
"schema": {
"$ref": "#/definitions/PageablePaymentResources"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Authentication required",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "Unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
}
},
"/api/v1/securities": {
"get": {
"tags": [
"Securities"
],
"summary": "Get and search all securities",
"description": "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.
",
"operationId": "getAndSearchAllSecurities",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "search",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "accountIds",
"in": "query",
"description": "Comma-separated list of identifiers of accounts",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "page",
"in": "query",
"description": "Result page that you want to retrieve.",
"required": false,
"type": "integer",
"default": 1,
"minimum": 1.0
},
{
"name": "perPage",
"in": "query",
"description": "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.",
"required": false,
"type": "integer",
"default": 20,
"maximum": 500.0,
"minimum": 1.0
},
{
"name": "order",
"in": "query",
"description": "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). ",
"required": false,
"type": "array",
"items": {
"type": "string",
"default": "id,ASC"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "List of requested securities",
"schema": {
"$ref": "#/definitions/PageableSecurityList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "3"
}
}
},
"/api/v1/securities/{ids}": {
"get": {
"tags": [
"Securities"
],
"summary": "Get multiple securities",
"description": "Get a list of multiple securities of the user that is authorized by the access_token. Must pass the securities' identifiers and the user's access_token. Securities whose identifiers do not exist or do not relate to the authorized user will not be contained in the result (If this applies to all of the given identifiers, then the result will be an empty list). 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.
WARNING: This service is deprecated and will be removed at some point. If you want to get multiple securities, please instead use the service 'Get and search all securities' and pass a comma-separated list of identifiers as a parameter 'ids'.
",
"operationId": "getMultipleSecurities",
"parameters": [
{
"name": "ids",
"in": "path",
"description": "Comma-separated list of identifiers of requested securities",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "csv",
"pattern": "[\\d]+,[\\d,]+"
}
],
"responses": {
"200": {
"description": "List of requested securities",
"schema": {
"$ref": "#/definitions/SecurityList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"deprecated": true,
"x-finapi": {
"order": "2"
}
}
},
"/api/v1/securities/{id}": {
"get": {
"tags": [
"Securities"
],
"summary": "Get a security",
"description": "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.
",
"operationId": "getSecurity",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Security identifier",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Requested security",
"schema": {
"$ref": "#/definitions/Security"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Security not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
}
},
"/api/v1/tests/checkCategorization": {
"post": {
"tags": [
"Mocks and Tests"
],
"summary": "Check categorization",
"description": "This service can be used to check the categorization for a given set of transactions, without the need of having the transactions actually imported in finAPI. The result of the categorization is the same as if the transactions were actually imported (the service regards the user-specific categorization rules of the user that is authorized by the access_token). Must pass the user's access_token.",
"operationId": "checkCategorization",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Transactions data",
"required": true,
"schema": {
"$ref": "#/definitions/CheckCategorizationData"
}
}
],
"responses": {
"200": {
"description": "List of given transaction IDs, mapped to their found category",
"schema": {
"$ref": "#/definitions/CategorizationCheckResults"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"422": {
"description": "The number of transactions exceeds the maximum limit",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "2"
}
}
},
"/api/v1/tests/mockBatchUpdate": {
"post": {
"tags": [
"Mocks and Tests"
],
"summary": "Mock batch update",
"description": "This service can be used to mock an update of one or several bank connections by letting you simulate finAPI's communication with a bank server. More specifically, you can provide custom balances and transactions for existing accounts and finAPI will import that data into the accounts as if the data had been delivered by a real bank server during a real update. The idea of this service is to allow you to create accounts with specific data in them so that you can test your application in different scenarios.
You can also test your application's reception and processing of push notifications with this service, by enabling the 'triggerNotifications' flag in your request. When this flag is enabled, finAPI will send notifications to your application based on the notification rules that are set up for the user and on the data you provided in the request, the same way as it works with finAPI's real automatic batch update process.
Note that this service behaves mostly like calling the bank connection update service, meaning that it returns immediately after having asynchronously started the update process, and also meaning that you have to check the status of the updated bank connections and accounts to find out when the update has finished and what the result is. As you can update several bank connections at once, this service is closer to how finAPI's automatic batch updates work as it is to the manual update service though. Because of this, the result of the mocked bank connection updates will be stored in the 'lastAutoUpdate' field of the bank connections and not in the 'lastManualUpdate' field. Also, just like with the real batch update, any bank connection that you use with this service must have a PIN stored (even though it is not actually forwarded to any bank server).
Also note that this service may be called only when the user's automatic bank connection updates are disabled, to make sure that the mock updates cannot intervene with a real update (please see the User field 'isAutoUpdateEnabled'). Also, it is currently not possible to mock data for security accounts with this service, as you can only pass transactions, but not security positions.
Please be aware that you will 'mess up' the accounts when using this service, meaning that when you perform a real update of accounts that you have previously updated with this service, finAPI might detect inconsistencies in the data that exists in its database and the data that is reported by the bank server, and try to fix this with the insertion of an adjusting entry ('Zwischensaldo' transaction). Also, new real transactions might not get imported as finAPI could match them to mocked transactions. THIS SERVICE IS MEANT FOR TESTING PURPOSES DURING DEVELOPMENT OF YOUR APPLICATION ONLY! This is why it will work only on the sandbox or alpha environments. Calling it on the live environment will result in 403 Forbidden.",
"operationId": "mockBatchUpdate",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Data for mock bank connection updates",
"required": true,
"schema": {
"$ref": "#/definitions/MockBatchUpdateParams"
}
}
],
"responses": {
"200": {
"description": "Mock batch update has been started (empty response body)"
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "You are not allowed to call this service (for instance, because automatic update is enabled for the user, or because you are trying to call the service on a live environment)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Bank connection or account not found; or account does not belong to the bank connection it is nested in.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "At least one of the given account identifiers refers to a security account; or at least one of the given bank connections is currently locked due to another running update; or not all given bank connections have a PIN stored; or the number of transactions exceeds the limit of 1000.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
}
},
"/api/v1/transactions": {
"get": {
"tags": [
"Transactions"
],
"summary": "Get and search all transactions",
"description": "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.",
"operationId": "getAndSearchAllTransactions",
"parameters": [
{
"name": "ids",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "view",
"in": "query",
"description": "This parameter defines finAPI's 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).",
"required": true,
"type": "string",
"enum": [
"bankView",
"userView"
]
},
{
"name": "search",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "counterpart",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "purpose",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "accountIds",
"in": "query",
"description": "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.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "minBankBookingDate",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "maxBankBookingDate",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "minFinapiBookingDate",
"in": "query",
"description": "Lower bound for a transaction's booking date as set by finAPI, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). For details about the meaning of the finAPI booking date, please see the field's documentation in the service's response.",
"required": false,
"type": "string"
},
{
"name": "maxFinapiBookingDate",
"in": "query",
"description": "Upper bound for a transaction's booking date as set by finAPI, in the format 'YYYY-MM-DD' (e.g. '2016-01-01'). For details about the meaning of the finAPI booking date, please see the field's documentation in the service's response.",
"required": false,
"type": "string"
},
{
"name": "minAmount",
"in": "query",
"description": "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",
"required": false,
"type": "number"
},
{
"name": "maxAmount",
"in": "query",
"description": "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",
"required": false,
"type": "number"
},
{
"name": "direction",
"in": "query",
"description": "If specified, then only transactions with the given direction(s) will be regarded. Use 'income' for regarding only received payments (amount >= 0), 'spending' for regarding only outgoing payments (amount < 0), or 'all' to regard both directions. If not specified, the direction defaults to 'all'.",
"required": false,
"type": "string",
"default": "all",
"enum": [
"all",
"income",
"spending"
]
},
{
"name": "labelIds",
"in": "query",
"description": "A comma-separated list of label identifiers. If specified, then only transactions that have been marked with at least one of the given labels will be contained in the result.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "categoryIds",
"in": "query",
"description": "A comma-separated list of category identifiers. If specified, then the result will contain only transactions whose category is either one of the given categories, or - but only if the 'includeChildCategories' flag is set to 'true' - whose category is a sub-category of one of the given categories. To include transactions without any category, pass the value '0' as the categoryId.",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
},
{
"name": "includeChildCategories",
"in": "query",
"description": "This flag controls how the given 'categoryIds' are handled. If set to 'true', then all transactions of a given categoryId, as well as all transactions of any of its sub-categories will be regarded. If set to 'false', then sub-categories of a given categoryId will not be regarded and only those transactions are regarded whose category matches one of the explicitly given categoryIds. The default value for this flag is 'true'.",
"required": false,
"type": "boolean",
"default": true
},
{
"name": "isNew",
"in": "query",
"description": "If specified, then only transactions that have their 'isNew' flag set to true/false will be regarded.",
"required": false,
"type": "boolean"
},
{
"name": "isPotentialDuplicate",
"in": "query",
"description": "If specified, then only transactions that have their 'isPotentialDuplicate' flag set to true/false will be regarded.",
"required": false,
"type": "boolean"
},
{
"name": "isAdjustingEntry",
"in": "query",
"description": "If specified, then only transactions that have their 'isAdjustingEntry' flag set to true/false will be regarded.",
"required": false,
"type": "boolean"
},
{
"name": "minImportDate",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "maxImportDate",
"in": "query",
"description": "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.",
"required": false,
"type": "string"
},
{
"name": "page",
"in": "query",
"description": "Result page that you want to retrieve.",
"required": false,
"type": "integer",
"default": 1,
"minimum": 1.0
},
{
"name": "perPage",
"in": "query",
"description": "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.",
"required": false,
"type": "integer",
"default": 20,
"maximum": 500.0,
"minimum": 1.0
},
{
"name": "order",
"in": "query",
"description": "Determines the order of the results. You can use the following fields for ordering the response: 'id', 'parentId', 'accountId', 'valueDate', 'bankBookingDate', 'finapiBookingDate', '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=finapiBookingDate,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). ",
"required": false,
"type": "array",
"items": {
"type": "string",
"default": "id,ASC"
},
"collectionFormat": "multi"
}
],
"responses": {
"200": {
"description": "List of requested transactions",
"schema": {
"$ref": "#/definitions/PageableTransactionList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "3"
}
},
"delete": {
"tags": [
"Transactions"
],
"summary": "Delete all transactions",
"description": "Delete a set, or the entirety, of transactions of the currently authorized user.",
"operationId": "deleteAllTransactions",
"parameters": [
{
"name": "maxDeletionDate",
"in": "query",
"description": "If specified, then only those transactions are being deleted whose 'finapiBookingDate' 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.",
"required": false,
"type": "string",
"maximum": 10.0,
"minimum": 10.0
},
{
"name": "safeMode",
"in": "query",
"description": "When passing 'true', then only those transactions are being deleted where at least one of the following holds true: 1. The transaction belongs to a 'demo connection'; 2. The transaction's 'potentialDuplicate' flag is set to TRUE; 3. The transaction is an adjusting entry ('Zwischensaldo' transaction) that was added by finAPI. When passing 'false', then finAPI will delete transactions independent of these characteristics. The default value for this parameter is 'true'.",
"required": false,
"type": "boolean",
"default": true,
"enum": [
"true",
"false"
]
},
{
"name": "rememberDeletion",
"in": "query",
"description": "When passing 'true', then finAPI will make sure to not re-import deleted transactions on future account updates. When 'false', then deleted transactions might be re-imported. Default value for this parameter is 'false'.",
"required": false,
"type": "boolean",
"default": false,
"enum": [
"true",
"false"
]
}
],
"responses": {
"200": {
"description": "List of identifiers of all deleted transactions",
"schema": {
"$ref": "#/definitions/IdentifierList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "11"
}
},
"patch": {
"tags": [
"Transactions"
],
"summary": "Edit multiple transactions",
"description": "Edit one or multiple transactions. You can edit the following fields: 'isNew=true|false' and/or 'isPotentialDuplicate=false' and/or 'categoryId=' and/or 'labelIds=[]'. To clear the category of the given transactions (so that they are no longer categorized), pass the value '0' as the categoryId. To clear the labels of the given transactions, pass an empty array of label identifiers: '[]'. The parameters 'categoryId' and 'labelIds' are forbidden if 'ids' is NOT set (i.e. you cannot update the category or labels for ALL transactions). The result is a list of identifiers of only those transactions that have changed as a result of this service call.",
"operationId": "editMultipleTransactions",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Update transactions parameters",
"required": true,
"schema": {
"$ref": "#/definitions/UpdateMultipleTransactionsParams"
}
}
],
"responses": {
"200": {
"description": "List of identifiers of all updated transactions",
"schema": {
"$ref": "#/definitions/IdentifierList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Category or labels not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "If 'isPotentialDuplicate' is set to 'true' (only 'false' is allowed)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "8"
}
}
},
"/api/v1/transactions/triggerCategorization": {
"post": {
"tags": [
"Transactions"
],
"summary": "Trigger categorization",
"description": "Triggers finAPI's background categorization process for all uncategorized transactions of the given bank connection(s) (or of all of the user's bank connections, if no bank connection identifiers are passed). The service returns as soon as the categorizations are scheduled. At this point, the bank connections will have their 'categorizationStatus' set to 'PENDING'. Use the service \"Get a bank connection\" or \"Get all bank connections\" to check when the categorization has finished (this is the case when the categorizationStatus has switched to 'READY').
Note that if at least one of the target bank connections is currently locked at the time when you call this service (i.e. the bank connection is currently being updated, or another categorization is already scheduled for it), then no categorization will be triggered at all and the service will respond with HTTP code 422.
Please also note:
• finAPI's background categorization process is executed automatically whenever you import or update a bank connection (though in case of update, it will categorize only the new transactions, and not re-run categorization for previously imported transactions). This means that in general you do not have to call this service after an import or update. Use this service only when you wish to re-run the categorization of all existing uncategorized transactions.
• if you wish to just manually assign categories to transactions, please use the service \"Edit a transaction\" or \"Edit multiple transactions\" instead.",
"operationId": "triggerCategorization",
"parameters": [
{
"in": "body",
"name": "body",
"description": "Trigger categorization parameters",
"required": true,
"schema": {
"$ref": "#/definitions/TriggerCategorizationParams"
}
}
],
"responses": {
"200": {
"description": "Categorizations have been scheduled (empty response body)"
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Given bank connection(s) not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "At least one of the target bank connections is currently locked, or there are no bank connections to trigger categorization for",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "9"
}
}
},
"/api/v1/transactions/{ids}": {
"get": {
"tags": [
"Transactions"
],
"summary": "Get multiple transactions",
"description": "Get a list of multiple transactions of the user that is authorized by the access_token. Must pass the transactions' identifiers and the user's access_token. Transactions whose identifiers do not exist or do not relate to the authorized user will not be contained in the result (If this applies to all of the given identifiers, then the result will be an empty list). WARNING: This service is deprecated and will be removed at some point. If you want to get multiple transactions, please instead use the service 'Get and search all transactions', where you can pass a comma-separated list of identifiers.",
"operationId": "getMultipleTransactions",
"parameters": [
{
"name": "ids",
"in": "path",
"description": "Comma-separated list of identifiers of requested transactions",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "csv",
"pattern": "[\\d]+,[\\d,]+"
}
],
"responses": {
"200": {
"description": "List of requested transactions",
"schema": {
"$ref": "#/definitions/TransactionList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"deprecated": true,
"x-finapi": {
"order": "2"
}
},
"patch": {
"tags": [
"Transactions"
],
"summary": "Edit multiple transactions (DEPRECATED)",
"description": "Change the fields of multiple transactions. You can change the following fields: 'isNew=true|false' and/or 'isPotentialDuplicate=false' and/or 'categoryId=' and/or 'labelIds=[]'. The max number of input identifiers is limited to 100. To clear the category of the given transactions (so that they are no longer categorized), pass the value '0' as the categoryId. To clear the labels of the given transactions, pass an empty array of label identifiers: '[]'. The result is a list of identifiers of only those transactions that have changed as a result of this service call. WARNING: This service is deprecated and will be removed at some point. If you want to edit multiple transactions, please instead use the service 'Edit multiple transactions', where you can pass a comma-separated list of identifiers.",
"operationId": "editMultipleTransactionsDeprecated",
"parameters": [
{
"name": "ids",
"in": "path",
"description": "Comma-separated list of identifiers of updated transactions",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "csv",
"pattern": "[\\d]+,[\\d,]+"
},
{
"in": "body",
"name": "body",
"description": "Update transactions parameters",
"required": true,
"schema": {
"$ref": "#/definitions/UpdateTransactionsParams"
}
}
],
"responses": {
"200": {
"description": "List of identifiers of all edited transactions",
"schema": {
"$ref": "#/definitions/IdentifierList"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Category or labels not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "If 'isPotentialDuplicate' is set to 'true' (only 'false' is allowed)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"deprecated": true,
"x-finapi": {
"order": "7"
}
}
},
"/api/v1/transactions/{id}": {
"get": {
"tags": [
"Transactions"
],
"summary": "Get a transaction",
"description": "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.",
"operationId": "getTransaction",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of transaction",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Requested transaction",
"schema": {
"$ref": "#/definitions/Transaction"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Transaction not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
},
"delete": {
"tags": [
"Transactions"
],
"summary": "Delete a transaction",
"description": "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 finAPI
Note that the 'Delete all transactions' service has additional functionality and allows you to delete transactions that you cannot delete with this service.",
"operationId": "deleteTransaction",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of transaction",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Transaction deleted (empty response body)"
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Transaction not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "Transaction cannot get deleted",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "10"
}
},
"patch": {
"tags": [
"Transactions"
],
"summary": "Edit a transaction",
"description": "Change a transaction's fields. You can change the following fields: 'isNew=true|false' and/or 'isPotentialDuplicate=false' and/or 'categoryId=' and/or 'labelIds=[]'. To clear a transaction's category (so that it is no longer categorized), pass the value '0' as the categoryId. To clear the labels of the given transaction, pass an empty array of label identifiers: '[]'.",
"operationId": "editTransaction",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of transaction",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
},
{
"in": "body",
"name": "body",
"description": "Update transactions parameters",
"required": true,
"schema": {
"$ref": "#/definitions/UpdateTransactionsParams"
}
}
],
"responses": {
"200": {
"description": "Edited transaction",
"schema": {
"$ref": "#/definitions/Transaction"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Transaction, category or labels not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "If 'isPotentialDuplicate' is set to 'true' (only 'false' is allowed)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "6"
}
}
},
"/api/v1/transactions/{id}/restore": {
"post": {
"tags": [
"Transactions"
],
"summary": "Restore a transaction",
"description": "Restore a previously split transaction. Removes all of its sub-transactions.",
"operationId": "restoreTransaction",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Transaction identifier",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Restored transaction",
"schema": {
"$ref": "#/definitions/Transaction"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Transaction not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "The request transaction is a sub-transaction and can not be restored.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "5"
}
}
},
"/api/v1/transactions/{id}/split": {
"post": {
"tags": [
"Transactions"
],
"summary": "Split a transaction",
"description": "Split a transaction into several logical sub-transactions. If the given transaction is split already, all its current sub-transactions will get deleted before the new sub-transactions will get created.",
"operationId": "splitTransaction",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Transaction identifier",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
},
{
"in": "body",
"name": "body",
"description": "Split transactions parameters",
"required": true,
"schema": {
"$ref": "#/definitions/SplitTransactionsParams"
}
}
],
"responses": {
"200": {
"description": "Split transaction",
"schema": {
"$ref": "#/definitions/Transaction"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Transaction, category or labels not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ILLEGAL_ENTITY_STATE if the transaction you are trying to split is a sub-transaction; ILLEGAL_FIELD_VALUE if there is less than two sub-transactions specified, or the specified sub-transactions' amounts do not add up to the original transaction's amount",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "4"
}
}
},
"/api/v1/users": {
"get": {
"tags": [
"Users"
],
"summary": "Get the authorized user",
"description": "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. This service returns the user's password as 'XXXXX'.",
"operationId": "getAuthorizedUser",
"responses": {
"200": {
"description": "Authorized user's data",
"schema": {
"$ref": "#/definitions/User"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
},
"post": {
"tags": [
"Users"
],
"summary": "Create a new user",
"description": "Create a new user. Must pass your global (i.e. client) access_token.
This service returns the user's password as plain text.
The automatic update of the user's bank connections is disabled by default for any new user. User identifiers are regarded case-insensitive by finAPI.
Please note that finAPI generally has a restricted set of allowed characters for input fields. You can find the allowed characters here. If a field does not explicitly specify a set of allowed characters, then these are the characters that are allowed for the field. Some fields may specify a different set of characters, in which case this will be documented for the field (like for the 'id' field in this service).
",
"operationId": "createUser",
"parameters": [
{
"in": "body",
"name": "body",
"description": "User's details",
"required": true,
"schema": {
"$ref": "#/definitions/UserCreateParams"
}
}
],
"responses": {
"201": {
"description": "Created user's data",
"schema": {
"$ref": "#/definitions/User"
}
},
"400": {
"description": "Bad request (for instance if the given password is too short/long)",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "ENTITY_EXISTS if the given userId already exists; ILLEGAL_ENTITY_STATE if you passed 'isAutoUpdateEnabled' = true, but the automatic update can't be enabled for this user (as it is disabled for the client).",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "3"
}
},
"delete": {
"tags": [
"Users"
],
"summary": "Delete the authorized user",
"description": "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). Note: finAPI will send a notification about the deletion of the user to each of your clients that has a user synchronization callback URL set in its configuration. This also includes the client that is performing this request.
",
"operationId": "deleteAuthorizedUser",
"responses": {
"200": {
"description": "User deleted (empty response body)"
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "User cannot get deleted at the moment as at least one of his bank connections is currently being imported or updated (either by the user or by finAPI's automatic batch update), or because the categorization of transactions is performed.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "8"
}
},
"patch": {
"tags": [
"Users"
],
"summary": "Edit the authorized user",
"description": "Edit the authorized user's data and settings. Must pass the user's access_token. Pass an empty string (but not null) to unset either the email or phone number. At least one field must have a non-null value in the request body. This service returns the user's password as 'XXXXX'.",
"operationId": "editAuthorizedUser",
"parameters": [
{
"in": "body",
"name": "body",
"description": "User's details",
"required": true,
"schema": {
"$ref": "#/definitions/UserUpdateParams"
}
}
],
"responses": {
"200": {
"description": "Edited user data",
"schema": {
"$ref": "#/definitions/User"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "The automatic update cannot be enabled",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "7"
}
}
},
"/api/v1/users/executePasswordChange": {
"post": {
"tags": [
"Users"
],
"summary": "Execute password change",
"description": "Change the password of a user. Must pass your global (i.e. client) access_token.
Note: When changing the password of a user, all tokens that have been handed out for that user (for whatever client) will be revoked! Also note that finAPI regards user identifiers case-insensitive.",
"operationId": "executePasswordChange",
"parameters": [
{
"in": "body",
"name": "body",
"required": false,
"schema": {
"$ref": "#/definitions/ExecutePasswordChangeParams"
}
}
],
"responses": {
"200": {
"description": "Password changed (empty response body)"
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role, or the given password change token is not valid",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "User not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "5"
}
}
},
"/api/v1/users/requestPasswordChange": {
"post": {
"tags": [
"Users"
],
"summary": "Request password change",
"description": "Request password change for a user. Must pass your global (i.e. client) access_token. Note that finAPI regards user identifiers case-insensitive.",
"operationId": "requestPasswordChange",
"parameters": [
{
"in": "body",
"name": "body",
"required": false,
"schema": {
"$ref": "#/definitions/RequestPasswordChangeParams"
}
}
],
"responses": {
"200": {
"description": "Details of change password request",
"schema": {
"$ref": "#/definitions/PasswordChangingResource"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "User not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "User is not verified",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "4"
}
}
},
"/api/v1/users/verificationStatus": {
"get": {
"tags": [
"Users"
],
"summary": "Get a user's verification status",
"description": "Get the verification status of the requested user. Must pass your global (i.e. client) access_token. Note that finAPI regards user identifiers case-insensitive.",
"operationId": "getVerificationStatus",
"parameters": [
{
"name": "userId",
"in": "query",
"description": "User's identifier",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User's verification status",
"schema": {
"$ref": "#/definitions/VerificationStatusResource"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "User not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "2"
}
}
},
"/api/v1/users/verify/{userId}": {
"post": {
"tags": [
"Users"
],
"summary": "Verify a user",
"description": "Verify a user. User verification is only required when your client does not have auto-verification enabled (see field 'isUserAutoVerificationEnabled' in Client Configuration Resource). Must pass your global (i.e. client) access_token. Note that finAPI regards user identifiers case-insensitive.",
"operationId": "verifyUser",
"parameters": [
{
"name": "userId",
"in": "path",
"description": "User's identifier",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User verified (empty response body)"
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "User not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "User already verified",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "6"
}
}
},
"/api/v1/users/{userId}": {
"delete": {
"tags": [
"Users"
],
"summary": "Delete an unverified user",
"description": "Delete an unverified user. Must pass your global (i.e. client) access_token.
Notes:
• Unverified users can only exist if the field 'isUserAutoVerificationEnabled' (see Client Configuration Resource) is set to 'false' (or had been false at some point in the past).
• finAPI will send a notification about the deletion of the user to each of your clients that has a user synchronization callback URL set in its configuration. This also includes the client that is performing this request.
• finAPI regards user identifiers case-insensitive.",
"operationId": "deleteUnverifiedUser",
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "User deleted (empty response body)"
},
"400": {
"description": "Identifier is not given",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "User not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"422": {
"description": "The user with the given identifier is already verified",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "9"
}
}
},
"/api/v1/webForms/{id}": {
"get": {
"tags": [
"Web Forms"
],
"summary": "Get a web form",
"description": "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 finAPI system after 24 hours after its creation.",
"operationId": "getWebForm",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Identifier of web form",
"required": true,
"type": "integer",
"pattern": "[\\d]+",
"format": "int64"
}
],
"responses": {
"200": {
"description": "Requested web form",
"schema": {
"$ref": "#/definitions/WebForm"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Not authenticated or invalid access_token",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"404": {
"description": "Web Form not found",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "1"
}
}
},
"/oauth/revoke": {
"post": {
"tags": [
"Authorization"
],
"summary": "Revoke a token",
"description": "An additional endpoint for the OAuth 2.0 Standard, which allows clients to notify finAPI that a previously obtained refresh_token or access_token is no longer required. A successful request will invalidate the given token. The revocation of a particular token may also cause the revocation of related tokens and the underlying authorization grant. For token_type_hint=access_token finAPI will invalidate only the given access_token. For token_type_hint=refresh_token, finAPI will invalidate the refresh token and all access tokens based on the same authorization grant. If the token_type_hint is not defined, finAPI will revoke all access and refresh tokens (if applicable) that are based on the same authorization grant.
Note that the service responds with HTTP status code 200 both if the token has been revoked successfully, and if the client submitted an invalid token.
Note also that the client's access_token is required to authenticate the revocation.
Here is an example of how to revoke a user's refresh_token (and therefore also his access tokens):Authorization: Bearer {client_access_token}\nPOST /oauth/revoke?token={refresh_token}&token_type_hint=refresh_token",
"operationId": "revokeToken",
"produces": [
"application/json"
],
"parameters": [
{
"name": "token",
"in": "query",
"description": "The token that the client wants to get revoked",
"required": true,
"type": "string"
},
{
"name": "token_type_hint",
"in": "query",
"description": "A hint about the type of the token submitted for revocation",
"required": false,
"type": "string",
"enum": [
"access_token",
"refresh_token"
]
}
],
"responses": {
"200": {
"description": "Token was invalidated successfully or token was invalid (empty response body)"
},
"400": {
"description": "The service does not support the revocation of the presented token type.",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"403": {
"description": "Incorrect authorization role",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"security": [
{
"finapi_auth": [
"all"
]
}
],
"x-finapi": {
"order": "2"
}
}
},
"/oauth/token": {
"post": {
"tags": [
"Authorization"
],
"summary": "Get tokens",
"description": "finAPI implements the OAuth 2.0 Standard for authorizing applications and users within applications. OAuth uses the terminology of clients and users. A client represents an application that calls finAPI services. A service call might be in the context of a user of the client (e.g.: getting a user's bank connections), or outside any user context (e.g.: editing your client's configuration, or creating a new user for your client). In any case, every service call must be authorized by an access_token. This service can be used to get such an access_token, for either one of the client's users, or for the client itself. Also, this service can be used to refresh the access_token of a user that has previously requested an access_token.
To get a token, you must always pass a valid client identifier and client secret (=client credentials). You can get free client credentials for the sandbox here. Alternatively, you can also contact us at [email protected].
The authorization process is similar for both a user within a client, and for the client itself:
• To authorize a client (i.e. application), use grant_type=client_credentials
• To authorize a user, use grant_type=password
If the given parameters are valid, the service will respond with the authorization data.
Here is an example of a response when authorizing a user:
{\n \"access_token\": \"yvMbx_TgwdYE0hgOVb8N4ZOvxOukqfjzYOGRZcJiCjQuRGkVIBfjjV3YG4zKTGiY2aPn2cQTGaQOT8uo5uo7_QOXts1s5UBSVuRHc6a8X30RrGBTyqV9h26SUHcZPNbZ\",\n \"token_type\": \"bearer\",\n \"refresh_token\": \"0b9KjiBVlZLz7a4HshSAIcFuscStiXT1VzT5mgNYwCQ_dWctTDsaIjedAhD1LpsOFJ7x6K8Emf8M3VOQkwNFR9FHijALYSQw2UeRwAC2MvrOKwfF1dHmOq5VEVYEaGf6\",\n \"expires_in\": 3600,\n \"scope\": \"all\"\n}
Use the returned access_token for other service calls by sending it in a 'Authorization' header, with the word 'Bearer' in front of the token. Like this:
Authorization: Bearer yvMbx_TgwdYE0hgOVb8N4ZOvxOukqfjzYOGRZcJiCjQuRGkVIBfjjV3YG4zKTGiY2aPn2cQTGaQOT8uo5uo7_QOXts1s5UBSVuRHc6a8X30RrGBTyqV9h26SUHcZPNbZ
WARNING: Sending the access_token as a request parameter is deprecated and will probably be no longer supported in the next release of finAPI. Please always send the access_token in the request header, as shown above.
By default, the access tokens have an expiration time of one hour (however, you can change this via the service PATCH /clientConfiguration). If a token has expired, then using the token for a service call will result in a HTTP code 401. To restore access you can simply get a new token (as it is described above) or use grant_type=refresh_token (which works for user-related tokens only). In the latter case you just have to pass the previously received refresh_token for the user.
If the user that you want to authorize is not yet verified by the client (please see the 'isUserAutoVerificationEnabled' flag in the Client Configuration), then the service will respond with HTTP code 403. If the user is locked (see 'maxUserLoginAttempts' in the Client Configuration), the service will respond with HTTP code 423.
If the current role has no privileges to call a certain service (e.g. if a user tries to create a new user, or if a client tries to access user data outside of any user context), then the request will fail with the HTTP code 403.
IMPORTANT NOTES:
• Even though finAPI is not logging query parameters, it is still recommended to pass the parameters in the POST body instead of in the URL. Also, please set the Content-Type of your request to 'application/x-www-form-urlencoded' when calling this service.
• You should use this service only when you actually need a new token. As long as a token exists and has not expired, the service will always return the same token for the same credentials. Calling this service repeatedly with the same credentials contradicts the idea behind the tokens in OAuth, and will have a negative impact on the performance of your application. So instead of retrieving the same tokens over and over with this service, you should cache the tokens and re-use them as long as they have not expired - or at least as long as you're using the same tokens repeatedly, e.g. for the time of an active user session in your application.
",
"operationId": "getToken",
"produces": [
"application/json"
],
"parameters": [
{
"name": "grant_type",
"in": "query",
"description": "Determines the required type of authorization:password - authorize a user; client_credentials - authorize a client;refresh_token - refresh a user's access_token.",
"required": true,
"type": "string",
"enum": [
"password",
"client_credentials",
"refresh_token"
]
},
{
"name": "client_id",
"in": "query",
"description": "Client identifier",
"required": true,
"type": "string"
},
{
"name": "client_secret",
"in": "query",
"description": "Client secret",
"required": true,
"type": "string"
},
{
"name": "refresh_token",
"in": "query",
"description": "Refresh token. Required for grant_type=refresh_token only.",
"required": false,
"type": "string"
},
{
"name": "username",
"in": "query",
"description": "User identifier. Required for grant_type=password only.",
"required": false,
"type": "string"
},
{
"name": "password",
"in": "query",
"description": "User password. Required for grant_type=password only.",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "Requested token",
"schema": {
"$ref": "#/definitions/AccessToken"
}
},
"400": {
"description": "Bad user credentials, or invalid refresh_token, or unsupported grant_type",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"401": {
"description": "Bad client credentials",
"schema": {
"$ref": "#/definitions/BadCredentialsError"
}
},
"403": {
"description": "User is not verified",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"423": {
"description": "User is locked",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
},
"500": {
"description": "An unexpected error occurred",
"schema": {
"$ref": "#/definitions/ErrorMessage"
}
}
},
"x-finapi": {
"order": "1"
}
}
}
},
"securityDefinitions": {
"finapi_auth": {
"type": "oauth2",
"authorizationUrl": "/oauth/authorize",
"tokenUrl": "/oauth/token",
"flow": "accessCode",
"scopes": {
"all": "modify any sources"
}
}
},
"definitions": {
"AccessToken": {
"type": "object",
"required": [
"access_token",
"expires_in",
"scope",
"token_type"
],
"properties": {
"token_type": {
"type": "string",
"example": "bearer",
"description": "Token type (it's always 'bearer')"
},
"scope": {
"type": "string",
"example": "all",
"description": "Requested scopes (it's always 'all')"
},
"refresh_token": {
"type": "string",
"example": "0b9KjiBVlZLz7a4HshSAIcFuscStiXT1VzT5mgNYwCQ_dWctTDsaIjedAhD1LpsOFJ7x6K8Emf8M3VOQkwNFR9FHijALYSQw2UeRwAC2MvrOKwfF1dHmOq5VEVYEaGf6",
"description": "Refresh token. Only set in case of grant_type='password'. Token has a length of up to 128 characters."
},
"access_token": {
"type": "string",
"example": "yvMbx_TgwdYE0hgOVb8N4ZOvxOukqfjzYOGRZcJiCjQuRGkVIBfjjV3YG4zKTGiY2aPn2cQTGaQOT8uo5uo7_QOXts1s5UBSVuRHc6a8X30RrGBTyqV9h26SUHcZPNbZ",
"description": "Access token. Token has a length of up to 128 characters."
},
"expires_in": {
"type": "integer",
"format": "int32",
"example": 3600,
"description": "Expiration time in seconds. A value of 0 means that the token never expires (unless it is explicitly invalidated, e.g. by revocation, or when a user gets locked)."
}
},
"description": "User access token info"
},
"Account": {
"type": "object",
"required": [
"accountNumber",
"accountTypeId",
"accountTypeName",
"bankConnectionId",
"id",
"isNew",
"status",
"supportedOrders"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Account identifier"
},
"bankConnectionId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier of the bank connection that this account belongs to"
},
"accountName": {
"type": "string",
"example": "Testaccount",
"description": "Account name"
},
"accountNumber": {
"type": "string",
"example": "12345678",
"description": "(National) account number. Note that this value might change whenever the account is updated (for example, leading zeros might be added or removed)."
},
"subAccountNumber": {
"type": "string",
"example": "1234",
"description": "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."
},
"iban": {
"type": "string",
"example": "DE89370400440532013000",
"description": "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."
},
"accountHolderName": {
"type": "string",
"example": "Herr Max Mustermann",
"description": "Name of the account holder"
},
"accountHolderId": {
"type": "string",
"example": "XXXXX",
"description": "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": {
"type": "string",
"example": "EUR",
"description": "Account's currency"
},
"accountTypeId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier of the account's type. Note that, in general, the type of an account can change any time when the account is being updated. This is subject to changes within the bank's internal account management. However, if the account's type has previously been changed explicitly (via the PATCH method), then the explicitly set type will NOT be automatically changed anymore, even if the type has changed on the bank side.
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
"
},
"accountTypeName": {
"type": "string",
"example": "Checking",
"description": "Name of the account's type"
},
"balance": {
"type": "number",
"example": 99.99,
"description": "Current account balance"
},
"overdraft": {
"type": "number",
"example": 99.99,
"description": "Current overdraft"
},
"overdraftLimit": {
"type": "number",
"example": 99.99,
"description": "Overdraft limit"
},
"availableFunds": {
"type": "number",
"example": 99.99,
"description": "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."
},
"lastSuccessfulUpdate": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Timestamp of when the account was last successfully updated (or initially imported); more precisely: time when the account data (balance and positions) has been stored into the finAPI databases. The value is returned in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
},
"lastUpdateAttempt": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Timestamp of when the account was last tried to be updated (or initially imported); more precisely: time when the update (or initial import) was triggered. The value is returned in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
},
"isNew": {
"description": "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.",
"example": true,
"type": "boolean"
},
"status": {
"type": "string",
"example": "UPDATED",
"description": "The current status of the account. Possible values are:
• UPDATED means that the account is up to date from finAPI's point of view. This means that no current import/update is running, and the previous import/update could successfully update the account's data (e.g. transactions and securities), and the bank given balance matched the transaction's calculated sum, meaning that no adjusting entry ('Zwischensaldo' transaction) was inserted.
• UPDATED_FIXED means that the account is up to date from finAPI's point of view (no current import/update is running, and the previous import/update could successfully update the account's data), BUT there was a deviation in the bank given balance which was fixed by adding an adjusting entry ('Zwischensaldo' transaction).
• DOWNLOAD_IN_PROGRESS means that the account's data is currently being imported/updated.
• DOWNLOAD_FAILED means that the account data could not get successfully imported or updated. Possible reasons: finAPI could not get the account's balance, or it could not parse all transactions/securities, or some internal error has occurred. Also, it could mean that finAPI could not even get to the point of receiving the account data from the bank server, for example because of incorrect login credentials or a network problem. Note however that when we get a balance and just an empty list of transactions or securities, then this is regarded as valid and successful download. The reason for this is that for some accounts that have little activity, we may actually get no recent transactions but only a balance.
• DEPRECATED means that the account could no longer get matched with any account from the bank server. This can mean either that the account was terminated by the user and is no longer sent by the bank server, or that finAPI could no longer match it because the account's data (name, type, iban, account number, etc.) has been changed by the bank.",
"enum": [
"UPDATED",
"UPDATED_FIXED",
"DOWNLOAD_IN_PROGRESS",
"DOWNLOAD_FAILED",
"DEPRECATED"
]
},
"supportedOrders": {
"type": "array",
"example": [
"SEPA_MONEY_TRANSFER",
"SEPA_COLLECTIVE_MONEY_TRANSFER",
"SEPA_BASIC_DIRECT_DEBIT",
"SEPA_BASIC_COLLECTIVE_DIRECT_DEBIT",
"SEPA_B2B_DIRECT_DEBIT",
"SEPA_B2B_COLLECTIVE_DIRECT_DEBIT"
],
"description": "List of orders that this account supports. Possible values are:
• SEPA_MONEY_TRANSFER - single money transfer
• SEPA_COLLECTIVE_MONEY_TRANSFER - collective money transfer
• SEPA_BASIC_DIRECT_DEBIT - single basic direct debit
• SEPA_BASIC_COLLECTIVE_DIRECT_DEBIT - collective basic direct debit
• SEPA_B2B_DIRECT_DEBIT - single Business-To-Business direct debit
• SEPA_B2B_COLLECTIVE_DIRECT_DEBIT - collective Business-To-Business direct debit
Note that this list may be empty if the account is not supporting any of the above orders. Also note that the list is refreshed each time the account is being updated, so available orders may get added or removed in the course of an account update.
",
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"SEPA_MONEY_TRANSFER",
"SEPA_COLLECTIVE_MONEY_TRANSFER",
"SEPA_BASIC_DIRECT_DEBIT",
"SEPA_BASIC_COLLECTIVE_DIRECT_DEBIT",
"SEPA_B2B_DIRECT_DEBIT",
"SEPA_B2B_COLLECTIVE_DIRECT_DEBIT"
]
}
},
"clearingAccounts": {
"type": "array",
"description": "List of clearing accounts that relate to this account. Clearing accounts can be used for money transfers (see field 'clearingAccountId' of the 'Request SEPA Money Transfer' service).",
"items": {
"$ref": "#/definitions/ClearingAccountData"
}
}
},
"description": "Container for a bank account's data"
},
"AccountList": {
"type": "object",
"properties": {
"accounts": {
"type": "array",
"description": "List of bank accounts",
"items": {
"$ref": "#/definitions/Account"
}
}
},
"description": "Container for data of multiple bank accounts"
},
"AccountParams": {
"type": "object",
"properties": {
"accountName": {
"type": "string",
"example": "Testaccount",
"description": "Account name. Maximum length is 512.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"accountTypeId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier of account type.
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
",
"minimum": 1.0,
"maximum": 7.0
},
"isNew": {
"description": "Whether this account should be flagged as '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 after every update of the bank connection.",
"example": true,
"type": "boolean"
}
},
"description": "Container for an account's name, type and 'isNew' flag'."
},
"BadCredentialsError": {
"type": "object",
"required": [
"error",
"error_description"
],
"properties": {
"error": {
"type": "string",
"example": "invalid_token",
"description": "Error type"
},
"error_description": {
"type": "string",
"example": "Not authenticated or invalid access_token",
"description": "Error description"
}
}
},
"Bank": {
"type": "object",
"required": [
"blz",
"blzs",
"health",
"id",
"isCustomerIdPassword",
"isSupported",
"isTestBank",
"name",
"pinsAreVolatile",
"popularity",
"supportedDataSources"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 277672,
"description": "Bank identifier.
NOTE: Do NOT assume that the identifiers of banks are the same across different finAPI environments. In fact, the identifiers may change whenever a new finAPI version is released, even within the same environment. The identifiers are meant to be used for references within the finAPI services only, but not for hard-coding them in your application. If you need to hard-code the usage of a certain bank within your application, please instead refer to the BLZ."
},
"name": {
"type": "string",
"example": "FinAPI Test Bank",
"description": "Name of bank"
},
"loginHint": {
"type": "string",
"example": "Bitte geben Sie Ihre Online-Identifikation und Ihre PIN ein.",
"description": "Login hint. Contains a German message for the user that explains what kind of credentials are expected.
Please note that it is strongly recommended to always show the login hint to the user if there is one, as the credentials that finAPI requires for the bank might be different to the credentials that the user knows from the bank's website.
Also note that the contents of this field should always be interpreted as HTML, as the text might contain HTML tags for highlighted words, paragraphs, etc."
},
"bic": {
"type": "string",
"example": "TESTBANKING",
"description": "BIC of bank"
},
"blz": {
"type": "string",
"example": "00000000",
"description": "BLZ of bank"
},
"blzs": {
"type": "array",
"example": [],
"description": "List of BLZs that belong to this bank. NOTE: This field is deprecated and will be removed at some point. Please refer to field 'blz' instead.",
"items": {
"type": "string"
}
},
"loginFieldUserId": {
"type": "string",
"example": "Onlinebanking-ID",
"description": "Label for the user ID login field, as it is called on the bank's website (e.g. \"Nutzerkennung\"). If this field is set (i.e. not null) then you should prompt your users to enter the required data in a text field which you can label with this field's value."
},
"loginFieldCustomerId": {
"type": "string",
"example": "Kunden-ID",
"description": "Label for the customer ID login field, as it is called on the bank's website (e.g. \"Kundennummer\"). If this field is set (i.e. not null) then you should prompt your users to enter the required data in a text field which you can label with this field's value."
},
"loginFieldPin": {
"type": "string",
"example": "PIN",
"description": "Label for the PIN field, as it is called on the bank's website (mostly \"PIN\"). If this field is set (i.e. not null) then you should prompt your users to enter the required data in a text field which you can label with this field's value."
},
"isCustomerIdPassword": {
"description": "Whether the banking customer ID has to be treated like a password. Certain banks require a second password (besides the PIN) for the user to login. In this case your application should use a password input field when prompting users for their credentials.",
"example": false,
"type": "boolean"
},
"isSupported": {
"description": "Whether this bank is supported by finAPI, i.e. whether you can import/update a bank connection of this bank.",
"example": true,
"type": "boolean"
},
"supportedDataSources": {
"type": "array",
"example": [
"FINTS_SERVER",
"WEB_SCRAPER"
],
"description": "List of the data sources that finAPI will use for data download for this bank. Possible values:
• FINTS_SERVER - means that finAPI will download data via the bank's FinTS interface.
• WEB_SCRAPER - means that finAPI will parse data from the bank's online banking website.
Note that this list will be empty for non-supported banks. Note also that web scraping might be disabled for your client (see GET /clientConfiguration). When this is the case, then finAPI will not use the web scraper for data download, and if the web scraper is the only supported data source of this bank, then finAPI will not allow to download any data for this bank at all (for details, see POST /bankConnections/import and POST /bankConnections/update).",
"items": {
"type": "string",
"enum": [
"WEB_SCRAPER",
"FINTS_SERVER"
]
}
},
"pinsAreVolatile": {
"description": "Whether the PINs that are used for authentication with the bank are volatile. If the PINs are volatile, it means that a PIN is usually valid only for a single authentication, and is then invalidated. If a bank uses volatile PINs, it is strongly inadvisable to store PINs in finAPI, as a stored PIN will not work for future authentications.",
"example": true,
"type": "boolean"
},
"location": {
"type": "string",
"example": "DE",
"description": "Bank location (two-letter country code; ISO 3166 ALPHA-2). Note that when this field is not set, it means that this bank depicts an international institute which is not bound to any specific country."
},
"city": {
"type": "string",
"example": "München",
"description": "City that this bank is located in. Note that this field may not be set for some banks."
},
"isTestBank": {
"description": "If true, then this bank does not depict a real bank, but rather a testing endpoint provided by a bank or by finAPI. You probably want to regard these banks only during the development of your application, but not in production. You can filter out these banks in production by making sure that the 'isTestBank' parameter is always set to 'false' whenever your application is calling the 'Get and search all banks' service.",
"example": true,
"type": "boolean"
},
"popularity": {
"type": "integer",
"format": "int32",
"example": 95,
"description": "Popularity of this bank with your users (mandator-wide, i.e. across all of your clients). The value equals the number of bank connections that are currently imported for this bank across all of your users (which means it is a constantly adjusting value). You can use this field for statistical evaluation, and also for ordering bank search results (see service 'Get and search all banks')."
},
"health": {
"type": "integer",
"format": "int32",
"example": 100,
"description": "The health status of this bank. This is a value between 0 and 100, depicting the percentage of successful communication attempts with this bank during the latest couple of bank connection imports or updates (across the entire finAPI system). Note that 'successful' means that there was no technical error trying to establish a communication with the bank. Non-technical errors (like incorrect credentials) are regarded successful communication attempts.",
"minimum": 0.0,
"maximum": 100.0
},
"lastCommunicationAttempt": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Time of the last communication attempt with this bank during a bank connection import or update (across the entire finAPI system). The value is returned in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
},
"lastSuccessfulCommunication": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Time of the last successful communication with this bank during a bank connection import or update (across the entire finAPI system). The value is returned in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
}
},
"description": "Container for a bank's data"
},
"BankConnection": {
"type": "object",
"required": [
"accountIds",
"bank",
"bankId",
"categorizationStatus",
"collectiveMoneyTransferSupported",
"ibanOnlyDirectDebitSupported",
"ibanOnlyMoneyTransferSupported",
"id",
"type",
"updateStatus"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Bank connection identifier"
},
"bankId": {
"type": "integer",
"format": "int64",
"example": 277672,
"description": "Identifier of the bank that this connection belongs to. NOTE: This field is DEPRECATED and will get removed at some point. Please refer to the 'bank' field instead."
},
"bank": {
"description": "Bank that this connection belongs to",
"$ref": "#/definitions/Bank"
},
"name": {
"type": "string",
"example": "Bank Connection",
"description": "Custom name for the bank connection. You can set this field with the 'Edit a bank connection' service, as well as during the initial import of the bank connection. Maximum length is 64."
},
"bankingUserId": {
"type": "string",
"example": "XXXXX",
"description": "Stored online banking user ID credential. This field may be null for the 'demo connection'. Note that if your client has no license for processing banking credentials then a banking user ID will always be 'XXXXX'."
},
"bankingCustomerId": {
"type": "string",
"example": "XXXXX",
"description": "Stored online banking customer ID credential. Note that if your client has no license for processing banking credentials or if this field contains a value that requires password protection (see field ‘isCustomerIdPassword’ in Bank Resource) then the banking customer ID will always be 'XXXXX'."
},
"bankingPin": {
"type": "string",
"example": "XXXXX",
"description": "Stored online banking PIN. If a PIN is stored, this will always be 'XXXXX'."
},
"type": {
"type": "string",
"example": "DEMO",
"description": "Bank connection type",
"enum": [
"ONLINE",
"DEMO"
]
},
"updateStatus": {
"type": "string",
"example": "READY",
"description": "Current status of data download (account balances and transactions/securities). The POST /bankConnections/import and POST /bankConnections//update services will set this flag to IN_PROGRESS before they return. Once the import or update has finished, the status will be changed to READY.",
"enum": [
"IN_PROGRESS",
"READY"
]
},
"categorizationStatus": {
"type": "string",
"example": "READY",
"description": "Current status of transactions categorization. The asynchronous download process that is triggered by a call of the POST /bankConnections/import and POST /bankConnections//update services (and also by finAPI's auto update, if enabled) will set this flag to PENDING once the download has finished and a categorization is scheduled for the imported transactions. A separate categorization thread will then start to categorize the transactions (during this process, the status is IN_PROGRESS). When categorization has finished, the status will be (re-)set to READY. Note that the current categorization status should only be queried after the download has finished, i.e. once the download status has switched from IN_PROGRESS to READY.",
"enum": [
"IN_PROGRESS",
"PENDING",
"READY"
]
},
"lastManualUpdate": {
"description": "Result of the last manual update of this bank connection. If no manual update has ever been done so far, then this field will not be set.",
"$ref": "#/definitions/UpdateResult"
},
"lastAutoUpdate": {
"description": "Result of the last auto update of this bank connection (ran by finAPI's automatic batch update process). If no auto update has ever been done so far, then this field will not be set.",
"$ref": "#/definitions/UpdateResult"
},
"twoStepProcedures": {
"type": "array",
"description": "Available two-step-procedures for this bank connection, used for submitting a money transfer or direct debit request (see /accounts/requestSepaMoneyTransfer or /requestSepaDirectDebit). The available two-step-procedures are re-evaluated each time this bank connection is updated (/bankConnections/update). This means that this list may change as a result of an update.",
"items": {
"$ref": "#/definitions/TwoStepProcedure"
}
},
"ibanOnlyMoneyTransferSupported": {
"description": "Whether this bank connection accepts money transfer requests where the recipient's account is defined just by the IBAN (without an additional BIC). This field is re-evaluated each time this bank connection is updated. See also: /accounts/requestSepaMoneyTransfer",
"example": true,
"type": "boolean"
},
"ibanOnlyDirectDebitSupported": {
"description": "Whether this bank connection accepts direct debit requests where the debitor's account is defined just by the IBAN (without an additional BIC). This field is re-evaluated each time this bank connection is updated. See also: /accounts/requestSepaDirectDebit",
"example": true,
"type": "boolean"
},
"collectiveMoneyTransferSupported": {
"description": "DEPRECATED! DO NOT USE THIS FIELD, AS IT IS UNRELIABLE. INSTEAD, REFER TO THE 'supportedOrders' FIELD IN THE ACCOUNT RESOURCE.
Whether this bank connection supports submitting collective money transfers. This field is re-evaluated each time this bank connection is updated. See also: /accounts/requestSepaMoneyTransfer",
"type": "boolean"
},
"defaultTwoStepProcedureId": {
"type": "string",
"example": "955",
"description": "The default two-step-procedure. Must match one of the available 'procedureId's from the 'twoStepProcedures' list. When this field is set, you can execute two-step-procedures (accounts/requestSepaMoneyTransfer or /requestSepaDirectDebit) without having to explicitly set a procedure. finAPI will use the default procedure in such cases. Note that the list of available procedures of a bank connection may change as a result of an update of the connection, and if this field references a procedure that is no longer available after an update, finAPI will automatically clear the default procedure (set it to null)."
},
"accountIds": {
"type": "array",
"example": [
1,
2,
3
],
"description": "Identifiers of the accounts that belong to this bank connection",
"items": {
"type": "integer",
"format": "int64"
}
},
"owners": {
"type": "array",
"description": "Information about the owner(s) of the bank connection",
"items": {
"$ref": "#/definitions/BankConnectionOwner"
}
}
},
"description": "Container for a bank connection's data"
},
"BankConnectionList": {
"type": "object",
"required": [
"connections"
],
"properties": {
"connections": {
"type": "array",
"description": "List of bank connections",
"items": {
"$ref": "#/definitions/BankConnection"
}
}
},
"description": "Container for data of multiple bank connections"
},
"BankConnectionOwner": {
"type": "object",
"properties": {
"firstName": {
"type": "string",
"example": "Max",
"description": "First name"
},
"lastName": {
"type": "string",
"example": "Mustermann",
"description": "Last name"
},
"salutation": {
"type": "string",
"example": "Herr",
"description": "Salutation"
},
"title": {
"type": "string",
"example": "Dr.",
"description": "Title"
},
"email": {
"type": "string",
"example": "[email protected]",
"description": "Email"
},
"dateOfBirth": {
"type": "string",
"example": "1980-01-01",
"description": "Date of birth (in format 'YYYY-MM-DD')"
},
"postCode": {
"type": "string",
"example": "80000",
"description": "Post code"
},
"country": {
"type": "string",
"example": "Deutschland",
"description": "Country"
},
"city": {
"type": "string",
"example": "München",
"description": "City"
},
"street": {
"type": "string",
"example": "Musterstraße",
"description": "Street"
},
"houseNumber": {
"type": "string",
"example": "99",
"description": "House number"
}
},
"description": "Container for a bank connection owner's data"
},
"BankList": {
"type": "object",
"required": [
"banks"
],
"properties": {
"banks": {
"type": "array",
"description": "Banks data",
"items": {
"$ref": "#/definitions/Bank"
}
}
},
"description": "Container for data of multiple banks"
},
"CashFlow": {
"type": "object",
"required": [
"balance",
"countAllTransactions",
"countIncomeTransactions",
"countSpendingTransactions",
"income",
"spending"
],
"properties": {
"category": {
"description": "Category of this cash flow. When null, then this is the cash flow of transactions that do not have a category.",
"$ref": "#/definitions/Category"
},
"income": {
"type": "number",
"example": 199.99,
"description": "The total calculated income for the given category"
},
"spending": {
"type": "number",
"example": -99.99,
"description": "The total calculated spending for the given category"
},
"balance": {
"type": "number",
"example": 100.0,
"description": "The calculated balance for the given category"
},
"countIncomeTransactions": {
"type": "integer",
"format": "int32",
"example": 5,
"description": "The total count of income transactions for the given category"
},
"countSpendingTransactions": {
"type": "integer",
"format": "int32",
"example": 3,
"description": "The total count of spending transactions for the given category"
},
"countAllTransactions": {
"type": "integer",
"format": "int32",
"example": 8,
"description": "The total count of all transactions for the given category"
}
},
"description": "Cash flow"
},
"CashFlowList": {
"type": "object",
"required": [
"cashFlows",
"totalBalance",
"totalIncome",
"totalSpending"
],
"properties": {
"cashFlows": {
"type": "array",
"description": "Array of cash flows",
"items": {
"$ref": "#/definitions/CashFlow"
}
},
"totalIncome": {
"type": "number",
"example": 199.99,
"description": "The total income"
},
"totalSpending": {
"type": "number",
"example": -99.99,
"description": "The total spending"
},
"totalBalance": {
"type": "number",
"example": 100.0,
"description": "The total balance"
}
},
"description": "Cash flows"
},
"CategorizationCheckResult": {
"type": "object",
"required": [
"transactionId"
],
"properties": {
"transactionId": {
"type": "string",
"example": "transaction",
"description": "Transaction identifier"
},
"category": {
"description": "Category",
"$ref": "#/definitions/Category"
}
}
},
"CategorizationCheckResults": {
"type": "object",
"required": [
"categorizationCheckResult"
],
"properties": {
"categorizationCheckResult": {
"type": "array",
"description": "List of results",
"items": {
"$ref": "#/definitions/CategorizationCheckResult"
}
}
}
},
"Category": {
"type": "object",
"required": [
"id",
"isCustom",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 378,
"description": "Category identifier.
NOTE: Do NOT assume that the identifiers of the global finAPI categories are the same across different finAPI environments. In fact, the identifiers may change whenever a new finAPI version is released, even within the same environment. The identifiers are meant to be used for references within the finAPI services only, but not for hard-coding them in your application. If you need to hard-code the usage of a certain global category within your application, please instead refer to the category name. Also, please make sure to check the 'isCustom' flag, which is false for all global categories (if you are not regarding this flag, you might end up referring to a user-specific category, and not the global category)."
},
"name": {
"type": "string",
"example": "Sport & Fitness",
"description": "Category name"
},
"parentId": {
"type": "integer",
"format": "int64",
"example": 373,
"description": "Identifier of the parent category (if a parent category exists)"
},
"parentName": {
"type": "string",
"example": "Freizeit, Hobbys & Soziales",
"description": "Name of the parent category (if a parent category exists)"
},
"isCustom": {
"description": "Whether the category is a finAPI global category (in which case this field will be false), or the category was created by a user (in which case this field will be true)",
"example": false,
"type": "boolean"
},
"children": {
"type": "array",
"example": [
1,
2,
3
],
"description": "List of sub-categories identifiers (if any exist)",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"description": "Category data"
},
"CategoryList": {
"type": "object",
"required": [
"categories"
],
"properties": {
"categories": {
"type": "array",
"description": "Categories",
"items": {
"$ref": "#/definitions/Category"
}
}
},
"description": "Container for data of multiple categories"
},
"CategoryParams": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "Sport & Fitness",
"description": "Name of the category. Maximum length is 128.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"parentId": {
"type": "integer",
"format": "int64",
"example": 373,
"description": "Identifier of the parent category, if the new category should be created as a sub-category. Must point to a main category in this case. If the new category should be a main category itself, this field must remain unset."
}
},
"description": "Category parameters"
},
"ChangeClientCredentialsParams": {
"type": "object",
"required": [
"clientId",
"newClientSecret",
"oldClientSecret"
],
"properties": {
"clientId": {
"type": "string",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"description": "client_id of the client that you want to change the secret for"
},
"oldClientSecret": {
"type": "string",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"description": "Old (=current) client_secret"
},
"newClientSecret": {
"type": "string",
"example": "01234567-89ab-cdef-0123-456789abcdef",
"description": "New client_secret. Required length is 36. Allowed symbols: Digits (0 through 9), lower-case and upper-case letters (A through Z), and the dash symbol (\"-\").",
"pattern": "[a-zA-Z0-9\\-]*"
}
},
"description": "Parameters for changing client credentials"
},
"CheckCategorizationData": {
"type": "object",
"required": [
"transactionData"
],
"properties": {
"transactionData": {
"type": "array",
"description": "Set of transaction data",
"items": {
"$ref": "#/definitions/CheckCategorizationTransactionData"
}
}
},
"description": "Transactions data for categorization check"
},
"CheckCategorizationTransactionData": {
"type": "object",
"required": [
"accountTypeId",
"amount",
"transactionId"
],
"properties": {
"transactionId": {
"type": "string",
"example": "transaction",
"description": "Identifier of transaction. This can be any arbitrary string that will be passed back in the response so that you can map the results to the given transactions. Note that the identifier must be unique within the given list of transactions."
},
"accountTypeId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier of account type.
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
",
"minimum": 1.0,
"maximum": 7.0
},
"amount": {
"type": "number",
"example": -99.99,
"description": "Amount"
},
"purpose": {
"type": "string",
"example": "Restaurantbesuch",
"description": "Purpose. Any symbols are allowed. Maximum length is 2000. Default value: null."
},
"counterpart": {
"type": "string",
"example": "Bar Centrale",
"description": "Counterpart. Any symbols are allowed. Maximum length is 80. Default value: null."
},
"counterpartIban": {
"type": "string",
"example": "DE13700800000061110500",
"description": "Counterpart IBAN. Default value: null."
},
"counterpartAccountNumber": {
"type": "string",
"example": "61110500",
"description": "Counterpart account number. Default value: null."
},
"counterpartBlz": {
"type": "string",
"example": "70080000",
"description": "Counterpart BLZ. Default value: null."
},
"counterpartBic": {
"type": "string",
"example": "DRESDEFF700",
"description": "Counterpart BIC. Default value: null."
},
"mcCode": {
"type": "string",
"example": "5542",
"description": "Merchant category code (for credit card transactions only). May only contain up to 4 digits. Default value: null."
},
"typeCodeZka": {
"type": "string",
"example": "999",
"description": "ZKA business transaction code which relates to the transaction's type (Number from 0 through 999). Default value: null."
}
},
"description": "Transaction data for categorization check"
},
"ClearingAccountData": {
"type": "object",
"required": [
"clearingAccountId",
"clearingAccountName"
],
"properties": {
"clearingAccountId": {
"type": "string",
"example": "BA-TUYEF7D24CGK6",
"description": "Technical identifier of the clearing account"
},
"clearingAccountName": {
"type": "string",
"example": "BA-TUYEF7D24CGK6",
"description": "Name of the clearing account"
}
}
},
"ClientConfiguration": {
"type": "object",
"required": [
"availableBankGroups",
"isAutomaticBatchUpdateEnabled",
"isMandatorAdmin",
"isUserAutoVerificationEnabled",
"isWebScrapingEnabled",
"maxUserLoginAttempts",
"paymentsEnabled",
"pinStorageAvailableInWebForm"
],
"properties": {
"isAutomaticBatchUpdateEnabled": {
"description": "Whether finAPI performs a regular automatic update of your users' bank connections. To find out how the automatic batch update is configured for your client, i.e. which bank connections get updated, and at which time and interval, please contact your Sys-Admin. Note that even if the automatic batch update is enabled for your client, individual users can still disable the feature for their own bank connections.",
"example": true,
"type": "boolean"
},
"userNotificationCallbackUrl": {
"type": "string",
"example": "https://bank.server.com/notification",
"description": "Callback URL to which finAPI sends the notification messages that are triggered from the automatic batch update of the users' bank connections. This field is only relevant if the automatic batch update is enabled for your client. For details about what the notification messages look like, please see the documentation in the 'Notification Rules' section. finAPI will call this URL with HTTP method POST. Note that the response of the call is not processed by finAPI. Also note that while the callback URL may be a non-secured (http) URL on the finAPI sandbox or alpha environment, it MUST be a SSL-secured (https) URL on the finAPI live system."
},
"userSynchronizationCallbackUrl": {
"type": "string",
"example": "https://bank.server.com/synchronization",
"description": "Callback URL for user synchronization. This field should be set if you - as a finAPI customer - have multiple clients using finAPI. In such case, all of your clients will share the same user base, making it possible for a user to be created in one client, but then deleted in another. To keep the client-side user data consistent in all clients, you should set a callback URL for each client. finAPI will send a notification to the callback URL of each client whenever a user of your user base gets deleted. Note that finAPI will send a deletion notification to ALL clients, including the one that made the user deletion request to finAPI. So when deleting a user in finAPI, a client should rely on the callback to delete the user on its own side. The notification that finAPI sends to the clients' callback URLs will be a POST request, with this body:
{\n \"userId\" : string // contains the identifier of the deleted user\n \"event\" : string // this will always be \"DELETED\"\n}
Note that finAPI does not process the response of this call. Also note that while the callback URL may be a non-secured (http) URL on the finAPI sandbox or alpha environment, it MUST be a SSL-secured (https) URL on the finAPI live system.As long as you have just one client, you can ignore this field and let it be null. However keep in mind that in this case your client will not receive any callback when a user gets deleted - so the deletion of the user on the client-side must not be forgotten. Of course you may still use the callback URL even for just one client, if you want to implement the deletion of the user on the client-side via the callback from finAPI."
},
"refreshTokensValidityPeriod": {
"type": "integer",
"format": "int32",
"example": 3600,
"description": "The validity period that newly requested refresh tokens initially have (in seconds). A value of 0 means that the tokens never expire (Unless explicitly invalidated, e.g. by revocation, or when a user gets locked, or when the password is reset for a user)."
},
"userAccessTokensValidityPeriod": {
"type": "integer",
"format": "int32",
"example": 3600,
"description": "The validity period that newly requested access tokens for users initially have (in seconds). A value of 0 means that the tokens never expire (Unless explicitly invalidated, e.g. by revocation, or when a user gets locked, or when the password is reset for a user)."
},
"clientAccessTokensValidityPeriod": {
"type": "integer",
"format": "int32",
"example": 3600,
"description": "The validity period that newly requested access tokens for clients initially have (in seconds). A value of 0 means that the tokens never expire (Unless explicitly invalidated, e.g. by revocation)."
},
"maxUserLoginAttempts": {
"type": "integer",
"format": "int32",
"example": 3,
"description": "Number of consecutive failed login attempts of a user into his finAPI account that is allowed before finAPI locks the user's account. When a user's account is locked, finAPI will invalidate all user's tokens and it will deny any service call in the context of this user (i.e. any call to a service using one of the user's authorization tokens, as well as the service for requesting a new token for this user). To unlock a user's account, a new password must be set for the account by the client (see the services /users/requestPasswordChange and /users/executePasswordChange). Once a new password has been set, all services will be available again for this user and the user's failed login attempts counter is reset to 0. The user's failed login attempts counter is also reset whenever a new authorization token has been successfully retrieved, or whenever the user himself changes his password.
Note that when this field has a value of 0, it means that there is no limit for user login attempts, i.e. finAPI will never lock user accounts."
},
"isUserAutoVerificationEnabled": {
"description": "Whether users that are created with this client are automatically verified on creation. If this field is set to 'false', then any user that is created with this client must first be verified with the \"Verify a user\" service before he can be authorized. If the field is 'true', then no verification is required by the client and the user can be authorized immediately after creation.",
"example": true,
"type": "boolean"
},
"isMandatorAdmin": {
"description": "Whether this client is a 'Mandator Admin'. Mandator Admins are special clients that can access the 'Mandator Administration' section of finAPI. If you do not yet have credentials for a Mandator Admin, please contact us at [email protected]. For further information, please refer to this article on our Dev Portal.",
"example": false,
"type": "boolean"
},
"isWebScrapingEnabled": {
"description": "Whether finAPI is allowed to use web scrapers for data download. If this field is set to 'true', then finAPI might download data from the online banking websites of banks (either in addition to using the FinTS interface, or as the sole data source for the download). If this field is set to 'false', then finAPI will not use any web scrapers and instead download data only from FinTS servers. For banks where no FinTS interface is available, finAPI will not allow any data download at all if web scraping is disabled for your client. Please contact your Sys-Admin if you want to change this setting.",
"example": true,
"type": "boolean"
},
"availableBankGroups": {
"type": "array",
"example": [
"DE",
"AT",
"IT"
],
"description": "List of bank groups that are available to this client. A bank group is a collection of all banks that are located in a certain country, and is defined by the country's ISO 3166 ALPHA-2 code (see also field 'location' of Bank resource). If you want to extend or limit the available bank groups for your client, please contact your Sys-Admin.
Note: There is no bank group for international institutes (i.e. institutes that are not bound to any specific country). Instead, those institutes are always available. If this list is empty, it means that ONLY international institutes are available.",
"items": {
"type": "string"
}
},
"applicationName": {
"type": "string",
"example": "My App",
"description": "Application name. When an application name is set (e.g. \"My App\"), then finAPI's web form will display a text to the user \"Weiterleitung auf finAPI von ...\" (e.g. \"Weiterleitung auf finAPI von MyApp\")."
},
"pinStorageAvailableInWebForm": {
"description": "Whether finAPI's web form will provide a checkbox for the user allowing him to choose whether to store his banking PIN in finAPI. If this field is set to false, then the user won't have an option to store his PIN.",
"example": true,
"type": "boolean"
},
"paymentsEnabled": {
"description": "Whether this client is allowed to do payments",
"example": true,
"type": "boolean"
}
},
"description": "Client configuration parameters"
},
"ClientConfigurationParams": {
"type": "object",
"properties": {
"userNotificationCallbackUrl": {
"type": "string",
"example": "https://bank.server.com/notification",
"description": "Callback URL to which finAPI sends the notification messages that are triggered from the automatic batch update of the users' bank connections. This field is only relevant if the automatic batch update is enabled for your client. For details about what the notification messages look like, please see the documentation in the 'Notification Rules' section. finAPI will call this URL with HTTP method POST. Note that the response of the call is not processed by finAPI. Also note that while the callback URL may be a non-secured (http) URL on the finAPI sandbox or alpha environment, it MUST be a SSL-secured (https) URL on the finAPI live system.The maximum allowed length of the URL is 512. If you have previously set a callback URL and now want to clear it (thus disabling user-related notifications altogether), you can pass an empty string (\"\")."
},
"userSynchronizationCallbackUrl": {
"type": "string",
"example": "https://bank.server.com/synchronization",
"description": "Callback URL for user synchronization. This field should be set if you - as a finAPI customer - have multiple clients using finAPI. In such case, all of your clients will share the same user base, making it possible for a user to be created in one client, but then deleted in another. To keep the client-side user data consistent in all clients, you should set a callback URL for each client. finAPI will send a notification to the callback URL of each client whenever a user of your user base gets deleted. Note that finAPI will send a deletion notification to ALL clients, including the one that made the user deletion request to finAPI. So when deleting a user in finAPI, a client should rely on the callback to delete the user on its own side.
The notification that finAPI sends to the clients' callback URLs will be a POST request, with this body:
{\n \"userId\" : string // contains the identifier of the deleted user\n \"event\" : string // this will always be \"DELETED\"\n}
Note that finAPI does not process the response of this call. Also note that while the callback URL may be a non-secured (http) URL on the finAPI sandbox or alpha system, it MUST be a SSL-secured (https) URL on the live system.As long as you have just one client, you can ignore this field and let it be null. However keep in mind that in this case your client will not receive any callback when a user gets deleted - so the deletion of the user on the client-side must not be forgotten. Of course you may still use the callback URL even for just one client, if you want to implement the deletion of the user on the client-side via the callback from finAPI. The maximum allowed length of the URL is 512. If you have previously set a callback URL and now want to clear it (thus disabling user synchronization related notifications for this client), you can pass an empty string (\"\")."
},
"refreshTokensValidityPeriod": {
"type": "integer",
"format": "int32",
"example": 3600,
"description": "The validity period that newly requested refresh tokens initially have (in seconds). The value must be greater than or equal to 60, or 0. A value of 0 means that the tokens never expire (Unless explicitly invalidated, e.g. by revocation , or when a user gets locked, or when the password is reset for a user)."
},
"userAccessTokensValidityPeriod": {
"type": "integer",
"format": "int32",
"example": 3600,
"description": "The validity period that newly requested access tokens for users initially have (in seconds). The value must be greater than or equal to 60, or 0. A value of 0 means that the tokens never expire."
},
"clientAccessTokensValidityPeriod": {
"type": "integer",
"format": "int32",
"example": 3600,
"description": "The validity period that newly requested access tokens for clients initially have (in seconds). The value must be greater than or equal to 60, or 0. A value of 0 means that the tokens never expire."
},
"isPinStorageAvailableInWebForm": {
"description": "Whether finAPI's web form should provide a checkbox for the user allowing him to choose whether to store his banking PIN in finAPI. If this field is set to false, then the user won't have an option to store his PIN.",
"example": true,
"type": "boolean"
},
"applicationName": {
"type": "string",
"example": "My App",
"description": "When an application name is set (e.g. \"My App\"), then finAPI's web form will display a text to the user \"Weiterleitung auf finAPI von ...\" (e.g. \"Weiterleitung auf finAPI von My App\"). If you have previously set a application name and now want to clear it, you can pass an empty string (\"\"). Maximum length: 64"
}
},
"description": "Client configuration parameters"
},
"DailyBalance": {
"type": "object",
"required": [
"balance",
"date",
"income",
"spending",
"transactions"
],
"properties": {
"date": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Date in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
},
"balance": {
"type": "number",
"example": 999.0,
"description": "Calculated balance at the end of day (aggregation of all regarded accounts)."
},
"income": {
"type": "number",
"example": 99.99,
"description": "The sum of income of the given day (aggregation of all regarded accounts)."
},
"spending": {
"type": "number",
"example": -99.99,
"description": "The sum of spending of the given day (aggregation of all regarded accounts)."
},
"transactions": {
"type": "array",
"example": [
1,
2,
3
],
"description": "Identifiers of the transactions for the given day",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"description": "Balance data for a single day"
},
"DailyBalanceList": {
"type": "object",
"required": [
"dailyBalances",
"paging"
],
"properties": {
"latestCommonBalanceTimestamp": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "The latestCommonBalanceTimestamp is the latest timestamp at which all regarded accounts have been up to date. Only balances with their date being smaller than the latestCommonBalanceTimestamp are reliable. Example: A user has two accounts: A (last update today, so balance from today) and B (last update yesterday, so balance from yesterday). The service /accounts/dailyBalances will return a balance for yesterday and for today, with the info latestCommonBalanceTimestamp=yesterday. Since account B might have received transactions this morning, today's balance might be wrong. So either make sure that all regarded accounts are up to date before calling this service, or use the results carefully in combination with the latestCommonBalanceTimestamp. The format is 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
},
"dailyBalances": {
"type": "array",
"description": "List of daily balances for the requested period and account(s)",
"items": {
"$ref": "#/definitions/DailyBalance"
}
},
"paging": {
"description": "Information for pagination",
"$ref": "#/definitions/Paging"
}
},
"description": "Contains a list of daily balances"
},
"DirectDebitOrderingResponse": {
"type": "object",
"required": [
"paymentId"
],
"properties": {
"successMessage": {
"type": "string",
"example": "Auftrag ausgeführt.",
"description": "Technical message from the bank server, confirming the success of the request. Typically, you would not want to present this message to the user. Note that this field may not be set. However if it is not set, it does not necessarily mean that there was an error in processing the request."
},
"warnMessage": {
"type": "string",
"example": "Es liegen Warnungen vor.",
"description": "In some cases, a bank server may accept the requested order, but return a warn message. This message may be of technical nature, but could also be of interest to the user."
},
"paymentId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Payment identifier. Can be used to retrieve the status of the payment (see 'Get payments' service)."
},
"challengeMessage": {
"type": "string",
"example": "Bitte geben Sie die TAN ein, die Sie per SMS erhalten.",
"description": "Message from the bank server containing information or instructions on how to retrieve the TAN that is needed to execute the requested order. This message should be presented to the user. Note that some bank servers may limit the message to just the most crucial information, e.g. the message may contain just a single number that depicts the target TAN number on a user's TAN list. You may want to parse the challenge message for such cases and extend it with more detailed information before showing it to the user."
},
"answerFieldLabel": {
"type": "string",
"example": "TAN-Nummer",
"description": "Suggestion from the bank server on how you can label your input field where the user must enter his TAN. A typical value that many bank servers give is 'TAN-Nummer'."
},
"tanListNumber": {
"type": "string",
"example": "001",
"description": "In case that the bank server has instructed the user to look up a TAN from a TAN list, this field may contain the identification number of the TAN list. However in most cases, this field is only set (i.e. not null) when the user has multiple active TAN lists."
},
"opticalData": {
"type": "string",
"example": "11048813833205002812775114302C30315D",
"description": "In case that the bank server has instructed the user to scan a flicker code, then this field will contain the raw data for the flicker animation as a BASE-64 string. Otherwise, this field will be not set (i.e. null). For more information on how to process the flicker code data, please address the finAPI Developer Portal."
},
"photoTanMimeType": {
"type": "string",
"example": "image/svg+xml",
"description": "In case that the 'photoTanData' field is set (i.e. not null), this field contains the MIME type to use for interpreting the photo data (e.g.: 'image/png')"
},
"photoTanData": {
"type": "string",
"example": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iaXNvLTg4NTktMSI/Pgo8IURPQ1RZUEUgc3ZnIFBVQkxJQyAiLS8vVzNDLy9EVEQgU1ZHIDEuMS8vRU4iICJodHRwOi8vd3d3LnczLm9yZy9HcmFwaGljcy9TVkcvMS4xL0RURC9zdmcxMS5kdGQiPgo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHZlcnNpb249IjEuMSIgdmlld0JveD0iMCAwIDIxMi43NTUgMjEyLjc1NSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgMjEyLjc1NSAyMTIuNzU1IiB3aWR0aD0iMTZweCIgaGVpZ2h0PSIxNnB4Ij4KICA8Zz4KICAgIDxwYXRoIGQ9Ik0xMDYuMzc3LDBDNDcuNzIxLDAsMCw0Ny43MjEsMCwxMDYuMzc3czQ3LjcyMSwxMDYuMzc3LDEwNi4zNzcsMTA2LjM3N3MxMDYuMzc3LTQ3LjcyMSwxMDYuMzc3LTEwNi4zNzcgICBTMTY1LjAzNCwwLDEwNi4zNzcsMHogTTEwNi4zNzcsMTk4Ljc1NUM1NS40NCwxOTguNzU1LDE0LDE1Ny4zMTQsMTQsMTA2LjM3N1M1NS40NCwxNCwxMDYuMzc3LDE0czkyLjM3Nyw0MS40NCw5Mi4zNzcsOTIuMzc3ICAgUzE1Ny4zMTQsMTk4Ljc1NSwxMDYuMzc3LDE5OC43NTV6IiBmaWxsPSIjMDAwMDAwIi8+CiAgICA8cGF0aCBkPSJtMTEzLjM3NywxMDAuMDk2di0zOS43NDRjMy45NjEsMS40NzEgNy40MTcsNC4xNyA5LjgyLDcuODIgMi4xMjcsMy4yMjkgNi40NjgsNC4xMjMgOS42OTYsMS45OTcgMy4yMjktMi4xMjYgNC4xMjMtNi40NjcgMS45OTYtOS42OTYtNS4wMjktNy42MzYtMTIuNzc4LTEyLjgyLTIxLjUxMi0xNC42NDd2LTExLjEyYzAtMy44NjYtMy4xMzQtNy03LTdzLTcsMy4xMzQtNyw3djExLjA5OWMtMTUuNDkzLDMuMjMtMjcuMTY4LDE2Ljk4OS0yNy4xNjgsMzMuNDI2IDAsMTYuNDM3IDExLjY3NiwzMC4xOTggMjcuMTY4LDMzLjQyOHYzOS43NDRjLTMuOTYxLTEuNDcxLTcuNDE3LTQuMTctOS44Mi03LjgyLTIuMTI3LTMuMjI5LTYuNDY4LTQuMTI0LTkuNjk2LTEuOTk3LTMuMjI5LDIuMTI2LTQuMTIzLDYuNDY3LTEuOTk2LDkuNjk2IDUuMDI5LDcuNjM2IDEyLjc3OCwxMi44MiAyMS41MTIsMTQuNjQ3djExLjExOWMwLDMuODY2IDMuMTM0LDcgNyw3czctMy4xMzQgNy03di0xMS4wOThjMTUuNDkzLTMuMjMgMjcuMTY4LTE2Ljk4OSAyNy4xNjgtMzMuNDI2LTIuODQyMTdlLTE0LTE2LjQzNy0xMS42NzUtMzAuMTk4LTI3LjE2OC0zMy40Mjh6bS0yNy4xNjgtMjAuODY1YzAtOC42NTMgNS40OTQtMTYuMDI3IDEzLjE2OC0xOC44NzR2MzcuNzQ4Yy03LjY3NC0yLjg0Ny0xMy4xNjgtMTAuMjIxLTEzLjE2OC0xOC44NzR6bTI3LjE2OCw3My4xNjZ2LTM3Ljc0OGM3LjY3NCwyLjg0NyAxMy4xNjgsMTAuMjIxIDEzLjE2OCwxOC44NzRzLTUuNDkzLDE2LjAyNy0xMy4xNjgsMTguODc0eiIgZmlsbD0iIzAwMDAwMCIvPgogIDwvZz4KPC9zdmc+Cg==",
"description": "In case that the bank server has instructed the user to scan a photo (or more generally speaking, any kind of QR-code-like data), then this field will contain the raw data of the photo as a BASE-64 string. Otherwise, this field will be not set (i.e. null). For more information on how to process the photo data, please address the finAPI Developer Portal."
}
},
"description": "Bank server's response to a direct debit order request"
},
"EditBankConnectionParams": {
"type": "object",
"properties": {
"bankingUserId": {
"type": "string",
"example": "123456",
"description": "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 finAPI's 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": {
"type": "string",
"example": "123456",
"description": "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 finAPI's 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": {
"type": "string",
"example": "123456",
"description": "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 finAPI's 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": {
"type": "string",
"example": "955",
"description": "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": {
"type": "string",
"example": "Bank Connection",
"description": "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 (\"\")."
}
},
"description": "Container for bank connection edit params"
},
"EditCategoryParams": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "Sport & Fitness",
"description": "New name of the category. Maximum length is 128.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
}
},
"description": "Container for category edit params"
},
"ErrorDetails": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "An unexpected error occurred",
"description": "Error message"
},
"code": {
"type": "string",
"example": "UNEXPECTED_ERROR",
"description": "Error code. See the documentation of the individual services for details about what values may be returned.",
"enum": [
"MISSING_FIELD",
"UNKNOWN_ENTITY",
"METHOD_NOT_ALLOWED",
"ENTITY_EXISTS",
"ILLEGAL_ENTITY_STATE",
"UNEXPECTED_ERROR",
"ILLEGAL_FIELD_VALUE",
"UNAUTHORIZED_ACCESS",
"BAD_REQUEST",
"UNSUPPORTED_ORDER",
"ILLEGAL_PAGE_SIZE",
"INVALID_FILTER_OPTIONS",
"TOO_MANY_IDS",
"BANK_SERVER_REJECTION",
"IBAN_ONLY_MONEY_TRANSFER_NOT_SUPPORTED",
"IBAN_ONLY_DIRECT_DEBIT_NOT_SUPPORTED",
"COLLECTIVE_MONEY_TRANSFER_NOT_SUPPORTED",
"INVALID_TWO_STEP_PROCEDURE",
"MISSING_TWO_STEP_PROCEDURE",
"UNSUPPORTED_MEDIA_TYPE",
"UNSUPPORTED_BANK",
"USER_NOT_VERIFIED",
"USER_ALREADY_VERIFIED",
"INVALID_TOKEN",
"LOCKED",
"NO_ACCOUNTS_FOR_TYPE_LIST",
"FORBIDDEN",
"NO_EXISTING_CHALLENGE",
"ADDITIONAL_AUTHENTICATION_REQUIRED",
"WEB_FORM_REQUIRED",
"WEB_FORM_ABORTED"
]
},
"type": {
"type": "string",
"example": "TECHNICAL",
"description": "Error type. BUSINESS errors depict German error messages for the user, e.g. from a bank server. TECHNICAL errors depict internal errors.",
"enum": [
"BUSINESS",
"TECHNICAL"
]
}
},
"description": "Error details"
},
"ErrorMessage": {
"type": "object",
"required": [
"authContext",
"date",
"endpoint",
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors",
"items": {
"$ref": "#/definitions/ErrorDetails"
}
},
"date": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Server date of when the error(s) occurred, in the format YYYY-MM-DD HH:MM:SS.SSS"
},
"requestId": {
"type": "string",
"example": "request-id-01234567890123456789",
"description": "ID of the request that caused this error. This is either what you have passed for the header 'X-REQUEST-ID', or an auto-generated ID in case you didn't pass any value for that header."
},
"endpoint": {
"type": "string",
"example": "https://finapi.localhost",
"description": "The service endpoint that was called"
},
"authContext": {
"type": "string",
"example": "1/2",
"description": "Information about the authorization context of the service call"
},
"bank": {
"type": "string",
"example": "00000000",
"description": "BLZ and name (in format \" - \") of a bank that was used for the original request"
}
},
"description": "Response type when a service call was not successful. Contains details about the error(s) that occurred."
},
"ExecutePasswordChangeParams": {
"type": "object",
"required": [
"password",
"passwordChangeToken",
"userId"
],
"properties": {
"userId": {
"type": "string",
"example": "username",
"description": "User identifier",
"pattern": "[a-zA-Z0-9\\-_\\.\\+@]*"
},
"password": {
"type": "string",
"example": "password",
"description": "User's new password. Minimum length is 6, and maximum length is 36.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"passwordChangeToken": {
"type": "string",
"example": "45a611d8-8a19-4a02-8726-a24b6a691ce9",
"description": "Decrypted password change token (the token that you received from the /users/requestPasswordChange service, decrypted with your data decryption key)",
"pattern": "[0-9a-f\\-]*"
}
},
"description": "Execute password change parameters"
},
"ExecuteSepaDirectDebitParams": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier of the bank account that you want to transfer money to"
},
"bankingTan": {
"type": "string",
"example": "0123",
"description": "Banking TAN that the user received from the bank for executing the direct debit order. The field is required if you are licensed to perform SEPA direct debits yourself. Otherwise, i.e. when finAPI's web form flow is required, the web form will deal with executing the service itself."
}
},
"description": "Container for parameters for the execution of a submitted SEPA direct debit order"
},
"ExecuteSepaMoneyTransferParams": {
"type": "object",
"required": [
"accountId"
],
"properties": {
"accountId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier of the bank account that you want to transfer money from"
},
"bankingTan": {
"type": "string",
"example": "098765",
"description": "Banking TAN that the user received from the bank for executing the money transfer order. The field is required if you are licensed to perform SEPA money transfers yourself. Otherwise, i.e. when finAPI's web form flow is required, the web form will deal with executing the service itself."
}
},
"description": "Container for parameters for the execution of a submitted SEPA money transfer order"
},
"IbanRule": {
"type": "object",
"required": [
"category",
"creationDate",
"direction",
"iban",
"id"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Rule identifier"
},
"category": {
"description": "The category that this rule assigns to the transactions that it matches",
"$ref": "#/definitions/Category"
},
"direction": {
"type": "string",
"example": "Income",
"description": "Direction for the rule. 'Income' means that the rule applies to transactions with a positive amount only, 'Spending' means it applies to transactions with a negative amount only.",
"enum": [
"Income",
"Spending"
]
},
"creationDate": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Timestamp of when the rule was created, in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)"
},
"iban": {
"type": "string",
"example": "DE89370400440532013000",
"description": "The IBAN for this rule"
}
},
"description": "Container for an IBAN rule"
},
"IbanRuleList": {
"type": "object",
"required": [
"ibanRules"
],
"properties": {
"ibanRules": {
"type": "array",
"description": "List of IBAN rules",
"items": {
"$ref": "#/definitions/IbanRule"
}
}
},
"description": "Container for IBAN rules"
},
"IbanRuleParams": {
"type": "object",
"required": [
"categoryId",
"direction",
"iban"
],
"properties": {
"categoryId": {
"type": "integer",
"format": "int64",
"example": 378,
"description": "ID of the category that this rule should assign to the matching transactions"
},
"direction": {
"type": "string",
"example": "Spending",
"description": "Direction for the rule. 'Income' means that the rule applies to transactions with a positive amount only, 'Spending' means it applies to transactions with a negative amount only. 'Both' means that it applies to both kind of transactions. Note that in case of 'Both', finAPI will create two individual rules (one with direction 'Income' and one with direction 'Spending').",
"enum": [
"Income",
"Spending",
"Both"
]
},
"iban": {
"type": "string",
"example": "DE89370400440532013000",
"description": "IBAN (case-insensitive)"
}
},
"description": "Parameters of IBAN rule"
},
"IbanRulesParams": {
"type": "object",
"required": [
"ibanRules"
],
"properties": {
"ibanRules": {
"type": "array",
"description": "IBAN rule definitions. The minimum number of rule definitions is 1. The maximum number of rule definitions is 100.",
"items": {
"$ref": "#/definitions/IbanRuleParams"
},
"maxItems": 100,
"minItems": 1
}
},
"description": "Params for creation IBAN rules"
},
"IdentifierList": {
"type": "object",
"properties": {
"identifiers": {
"type": "array",
"example": [
1,
2,
3
],
"description": "Set of identifiers (in ascending order)",
"uniqueItems": true,
"items": {
"type": "integer",
"format": "int64"
}
}
},
"description": "Set of identifiers (in ascending order)"
},
"IdentifiersParams": {
"type": "object",
"required": [
"ids"
],
"properties": {
"ids": {
"type": "array",
"example": [
1,
2,
3
],
"description": "List of identifiers",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"description": "Identifiers params"
},
"ImportBankConnectionParams": {
"type": "object",
"required": [
"bankId"
],
"properties": {
"bankId": {
"type": "integer",
"format": "int64",
"example": 277672,
"description": "Bank Identifier"
},
"bankingUserId": {
"type": "string",
"example": "123456",
"description": "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 finAPI's web form, this field can contain any value. It will be ignored."
},
"bankingCustomerId": {
"type": "string",
"example": "123456",
"description": "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 finAPI's web form, this field can contain any value. It will be ignored."
},
"bankingPin": {
"type": "string",
"example": "123456",
"description": "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 finAPI's web form, this field can be left unset or contain any value. It will be ignored."
},
"storePin": {
"default": false,
"description": "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 finAPI's 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).",
"example": true,
"type": "boolean"
},
"name": {
"type": "string",
"example": "Bank connection",
"description": "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": {
"default": false,
"description": "Whether to skip the download of transactions and securities or not. If set to true, then finAPI 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 finAPI 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 finAPI's 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. finAPI will always download transactions for Bausparen accounts.
",
"example": false,
"type": "boolean"
},
"loadOwnerData": {
"default": false,
"description": "Whether to load information about the bank connection owner(s) - see field 'owners'. Default value is 'false'.",
"example": false,
"type": "boolean"
},
"maxDaysForDownload": {
"type": "integer",
"format": "int32",
"example": 365,
"description": "Use this parameter if you want to limit the date range for transactions download. The value depicts the number of days that finAPI 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 finAPI will try to get all transactions that it can. Please note that when you specify the parameter there is no guarantee that finAPI 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; finAPI will always download all positions that it can get.
This flag is currently not guaranteed to work for all banks!",
"default": 0
},
"accountTypeIds": {
"type": "array",
"example": [
1,
2,
3,
4,
5,
6,
7,
8
],
"description": "Whitelist of identifiers of finAPI 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!",
"items": {
"type": "integer",
"format": "int64"
}
},
"challengeResponse": {
"type": "string",
"example": "0123",
"description": "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 finAPI's web form flow, finAPI will automatically deal with getting the challenge response from the user via the web form."
}
},
"description": "Container for bank connection import parameters"
},
"KeywordRule": {
"type": "object",
"required": [
"category",
"creationDate",
"direction",
"id",
"keywords"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Rule identifier"
},
"category": {
"description": "The category that this rule assigns to the transactions that it matches",
"$ref": "#/definitions/Category"
},
"direction": {
"type": "string",
"example": "Spending",
"description": "Direction for the rule. 'Income' means that the rule applies to transactions with a positive amount only, 'Spending' means it applies to transactions with a negative amount only.",
"enum": [
"Income",
"Spending"
]
},
"creationDate": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Timestamp of when the rule was created, in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)"
},
"keywords": {
"type": "array",
"example": [
"coffee",
"pizza",
"burger"
],
"description": "Set of keywords that this rule defines.",
"items": {
"type": "string"
}
}
},
"description": "Container for a keyword rule"
},
"KeywordRuleList": {
"type": "object",
"required": [
"keywordRules"
],
"properties": {
"keywordRules": {
"type": "array",
"description": "List of keyword rules",
"items": {
"$ref": "#/definitions/KeywordRule"
}
}
},
"description": "Container for keyword rules"
},
"KeywordRuleParams": {
"type": "object",
"required": [
"categoryId",
"direction",
"keywords"
],
"properties": {
"categoryId": {
"type": "integer",
"format": "int64",
"example": 378,
"description": "ID of the category that this rule should assign to the matching transactions"
},
"direction": {
"type": "string",
"example": "Spending",
"description": "Direction for the rule. 'Income' means that the rule applies to transactions with a positive amount only, 'Spending' means it applies to transactions with a negative amount only. 'Both' means that it applies to both kind of transactions. Note that in case of 'Both', finAPI will create two individual rules (one with direction 'Income' and one with direction 'Spending').",
"enum": [
"Income",
"Spending",
"Both"
]
},
"keywords": {
"type": "array",
"example": [
"coffee",
"pizza",
"burger"
],
"description": "Set of keywords for the rule (Keywords are regarded case-insensitive). The minimum number of keywords is 1. The maximum number of keywords is 100.",
"items": {
"type": "string"
},
"maxItems": 100,
"minItems": 1
}
},
"description": "Parameters of keyword rule"
},
"KeywordRulesParams": {
"type": "object",
"required": [
"keywordRules"
],
"properties": {
"keywordRules": {
"type": "array",
"description": "Keyword rule definitions. The minimum number of rule definitions is 1. The maximum number of rule definitions is 100.",
"items": {
"$ref": "#/definitions/KeywordRuleParams"
},
"maxItems": 100,
"minItems": 1
}
},
"description": "Params for creation keyword rules"
},
"Label": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Label identifier"
},
"name": {
"type": "string",
"example": "test",
"description": "Label name"
}
},
"description": "Container for a label's data"
},
"LabelList": {
"type": "object",
"required": [
"labels"
],
"properties": {
"labels": {
"type": "array",
"description": "Data of labels",
"items": {
"$ref": "#/definitions/Label"
}
}
},
"description": "Container for data of multiple labels"
},
"LabelParams": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "test",
"description": "Label's name. Maximum length is 288.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
}
},
"description": "Label's name"
},
"MockAccountData": {
"type": "object",
"required": [
"accountBalance",
"accountId"
],
"properties": {
"accountId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Account identifier"
},
"accountBalance": {
"type": "number",
"example": 99.99,
"description": "The balance that this account should be set to. Note that when the balance does not add up to the current balance plus the sum of the transactions you pass in the 'newTransactions' field, finAPI will fix the balance deviation with the insertion of an adjusting entry ('Zwischensaldo' transaction)."
},
"newTransactions": {
"type": "array",
"description": "New transactions that should be imported into the account (maximum 1000 transactions at once). Please make sure that the value you pass in the 'accountBalance' field equals the current account balance plus the sum of the new transactions that you pass here, otherwise finAPI will detect a deviation in the balance and fix it with the insertion of an adjusting entry ('Zwischensaldo' transaction). Please also note that it is not guaranteed that all transactions that you pass here will actually get imported. More specifically, finAPI will ignore any transactions whose booking date is prior to the booking date of the latest currently existing transactions minus 10 days (which is the 'update window' that finAPI uses when importing new transactions). Also, finAPI will ignore any transactions that are considered duplicates of already existing transactions within the update window. This is the case for instance when you try to import a new transaction with the same booking date and same amount as an already existing transaction. In such cases, you might get an adjusting entry too ('Zwischensaldo' transaction), as your given balance might not add up to the transactions that will exist in the account after the update.",
"items": {
"$ref": "#/definitions/NewTransaction"
}
}
},
"description": "Mock account data"
},
"MockBankConnectionUpdate": {
"type": "object",
"required": [
"bankConnectionId"
],
"properties": {
"bankConnectionId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Bank connection identifier"
},
"simulateBankLoginError": {
"default": false,
"description": "Whether to simulate the case that the update fails due to incorrect banking credentials. Note that there is no real communication to any bank server involved, so you won't lock your accounts when enabling this flag. Default value is 'false'.",
"example": false,
"type": "boolean"
},
"mockAccountsData": {
"type": "array",
"description": "Mock accounts data. Note that for accounts that exist in a bank connection but that you do not specify in this list, the service will act like those accounts are not received by the bank servers. This means that any accounts that you do not specify here will be marked as deprecated. If you do not specify this list at all, all accounts in the bank connection will be marked as deprecated.",
"items": {
"$ref": "#/definitions/MockAccountData"
}
}
},
"description": "Data for a mock bank connection update"
},
"MockBatchUpdateParams": {
"type": "object",
"required": [
"mockBankConnectionUpdates"
],
"properties": {
"mockBankConnectionUpdates": {
"type": "array",
"description": "List of mock bank connection updates",
"items": {
"$ref": "#/definitions/MockBankConnectionUpdate"
}
},
"triggerNotifications": {
"default": false,
"description": "Whether this call should trigger the dispatching of notifications. Default is 'false'.",
"example": true,
"type": "boolean"
}
},
"description": "Data for mock bank connection updates"
},
"MoneyTransferOrderingResponse": {
"type": "object",
"required": [
"paymentId"
],
"properties": {
"successMessage": {
"type": "string",
"example": "Auftrag ausgeführt.",
"description": "Technical message from the bank server, confirming the success of the request. Typically, you would not want to present this message to the user. Note that this field may not be set. However if it is not set, it does not necessarily mean that there was an error in processing the request."
},
"warnMessage": {
"type": "string",
"example": "Es liegen Warnungen vor.",
"description": "In some cases, a bank server may accept the requested order, but return a warn message. This message may be of technical nature, but could also be of interest to the user."
},
"paymentId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Payment identifier. Can be used to retrieve the status of the payment (see 'Get payments' service)."
},
"challengeMessage": {
"type": "string",
"example": "Bitte geben Sie die TAN ein, die Sie per SMS erhalten.",
"description": "Message from the bank server containing information or instructions on how to retrieve the TAN that is needed to execute the requested order. This message should be presented to the user. Note that some bank servers may limit the message to just the most crucial information, e.g. the message may contain just a single number that depicts the target TAN number on a user's TAN list. You may want to parse the challenge message for such cases and extend it with more detailed information before showing it to the user."
},
"answerFieldLabel": {
"type": "string",
"example": "TAN-Nummer",
"description": "Suggestion from the bank server on how you can label your input field where the user must enter his TAN. A typical value that many bank servers give is 'TAN-Nummer'."
},
"tanListNumber": {
"type": "string",
"example": "001",
"description": "In case that the bank server has instructed the user to look up a TAN from a TAN list, this field may contain the identification number of the TAN list. However in most cases, this field is only set (i.e. not null) when the user has multiple active TAN lists."
},
"opticalData": {
"type": "string",
"example": "11048813833205002812775114302C30315D",
"description": "In case that the bank server has instructed the user to scan a flicker code, then this field will contain the raw data for the flicker animation as a BASE-64 string. Otherwise, this field will be not set (i.e. null). For more information on how to process the flicker code data, please address the finAPI Developer Portal."
},
"photoTanMimeType": {
"type": "string",
"example": "image/svg+xml",
"description": "In case that the 'photoTanData' field is set (i.e. not null), this field contains the MIME type to use for interpreting the photo data (e.g.: 'image/png')"
},
"photoTanData": {
"type": "string",
"example": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iaXNvLTg4NTktMSI/Pgo8IURPQ1RZUEUgc3ZnIFBVQkxJQyAiLS8vVzNDLy9EVEQgU1ZHIDEuMS8vRU4iICJodHRwOi8vd3d3LnczLm9yZy9HcmFwaGljcy9TVkcvMS4xL0RURC9zdmcxMS5kdGQiPgo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHZlcnNpb249IjEuMSIgdmlld0JveD0iMCAwIDIxMi43NTUgMjEyLjc1NSIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgMjEyLjc1NSAyMTIuNzU1IiB3aWR0aD0iMTZweCIgaGVpZ2h0PSIxNnB4Ij4KICA8Zz4KICAgIDxwYXRoIGQ9Ik0xMDYuMzc3LDBDNDcuNzIxLDAsMCw0Ny43MjEsMCwxMDYuMzc3czQ3LjcyMSwxMDYuMzc3LDEwNi4zNzcsMTA2LjM3N3MxMDYuMzc3LTQ3LjcyMSwxMDYuMzc3LTEwNi4zNzcgICBTMTY1LjAzNCwwLDEwNi4zNzcsMHogTTEwNi4zNzcsMTk4Ljc1NUM1NS40NCwxOTguNzU1LDE0LDE1Ny4zMTQsMTQsMTA2LjM3N1M1NS40NCwxNCwxMDYuMzc3LDE0czkyLjM3Nyw0MS40NCw5Mi4zNzcsOTIuMzc3ICAgUzE1Ny4zMTQsMTk4Ljc1NSwxMDYuMzc3LDE5OC43NTV6IiBmaWxsPSIjMDAwMDAwIi8+CiAgICA8cGF0aCBkPSJtMTEzLjM3NywxMDAuMDk2di0zOS43NDRjMy45NjEsMS40NzEgNy40MTcsNC4xNyA5LjgyLDcuODIgMi4xMjcsMy4yMjkgNi40NjgsNC4xMjMgOS42OTYsMS45OTcgMy4yMjktMi4xMjYgNC4xMjMtNi40NjcgMS45OTYtOS42OTYtNS4wMjktNy42MzYtMTIuNzc4LTEyLjgyLTIxLjUxMi0xNC42NDd2LTExLjEyYzAtMy44NjYtMy4xMzQtNy03LTdzLTcsMy4xMzQtNyw3djExLjA5OWMtMTUuNDkzLDMuMjMtMjcuMTY4LDE2Ljk4OS0yNy4xNjgsMzMuNDI2IDAsMTYuNDM3IDExLjY3NiwzMC4xOTggMjcuMTY4LDMzLjQyOHYzOS43NDRjLTMuOTYxLTEuNDcxLTcuNDE3LTQuMTctOS44Mi03LjgyLTIuMTI3LTMuMjI5LTYuNDY4LTQuMTI0LTkuNjk2LTEuOTk3LTMuMjI5LDIuMTI2LTQuMTIzLDYuNDY3LTEuOTk2LDkuNjk2IDUuMDI5LDcuNjM2IDEyLjc3OCwxMi44MiAyMS41MTIsMTQuNjQ3djExLjExOWMwLDMuODY2IDMuMTM0LDcgNyw3czctMy4xMzQgNy03di0xMS4wOThjMTUuNDkzLTMuMjMgMjcuMTY4LTE2Ljk4OSAyNy4xNjgtMzMuNDI2LTIuODQyMTdlLTE0LTE2LjQzNy0xMS42NzUtMzAuMTk4LTI3LjE2OC0zMy40Mjh6bS0yNy4xNjgtMjAuODY1YzAtOC42NTMgNS40OTQtMTYuMDI3IDEzLjE2OC0xOC44NzR2MzcuNzQ4Yy03LjY3NC0yLjg0Ny0xMy4xNjgtMTAuMjIxLTEzLjE2OC0xOC44NzR6bTI3LjE2OCw3My4xNjZ2LTM3Ljc0OGM3LjY3NCwyLjg0NyAxMy4xNjgsMTAuMjIxIDEzLjE2OCwxOC44NzRzLTUuNDkzLDE2LjAyNy0xMy4xNjgsMTguODc0eiIgZmlsbD0iIzAwMDAwMCIvPgogIDwvZz4KPC9zdmc+Cg==",
"description": "In case that the bank server has instructed the user to scan a photo (or more generally speaking, any kind of QR-code-like data), then this field will contain the raw data of the photo as a BASE-64 string. Otherwise, this field will be not set (i.e. null). For more information on how to process the photo data, please address the finAPI Developer Portal."
}
},
"description": "Bank server's response to a money transfer order request"
},
"MonthlyUserStats": {
"type": "object",
"required": [
"maxBankConnectionCount",
"minBankConnectionCount",
"month"
],
"properties": {
"month": {
"type": "string",
"example": "2018-01",
"description": "The month that the contained information applies to, in the format 'YYYY-MM'."
},
"minBankConnectionCount": {
"type": "integer",
"format": "int32",
"example": 1,
"description": "Minimum count of bank connections that this user has had at any point during the month."
},
"maxBankConnectionCount": {
"type": "integer",
"format": "int32",
"example": 5,
"description": "Maximum count of bank connections that this user has had at any point during the month."
}
},
"description": "Information about a user's data or activities for a certain month"
},
"NewTransaction": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"example": -99.99,
"description": "Amount. Required."
},
"purpose": {
"type": "string",
"example": "Restaurantbesuch",
"description": "Purpose. Any symbols are allowed. Maximum length is 2000. Optional. Default value: null."
},
"counterpart": {
"type": "string",
"example": "Bar Centrale",
"description": "Counterpart. Any symbols are allowed. Maximum length is 80. Optional. Default value: null."
},
"counterpartIban": {
"type": "string",
"example": "DE13700800000061110500",
"description": "Counterpart IBAN. Optional. Default value: null."
},
"counterpartBlz": {
"type": "string",
"example": "70080000",
"description": "Counterpart BLZ. Optional. Default value: null."
},
"counterpartBic": {
"type": "string",
"example": "DRESDEFF700",
"description": "Counterpart BIC. Optional. Default value: null."
},
"counterpartAccountNumber": {
"type": "string",
"example": "61110500",
"description": "Counterpart account number. Maximum length is 34. Optional. Default value: null."
},
"bookingDate": {
"type": "string",
"example": "2018-01-01",
"description": "Booking date in the format 'YYYY-MM-DD'.
If the date lies back more than 10 days from the booking date of the latest transaction that currently exists in the account, then this transaction will be ignored and not imported. If the date depicts a date in the future, then finAPI will deal with it the same way as it does with real transactions during a real update (see fields 'bankBookingDate' and 'finapiBookingDate' in the Transaction Resource for explanation).
This field is optional, default value is the current date."
},
"valueDate": {
"type": "string",
"example": "2018-01-01",
"description": "Value date in the format 'YYYY-MM-DD'. Optional. Default value: Same as the booking date."
}
},
"description": "Mock transaction data"
},
"NotificationRule": {
"type": "object",
"required": [
"id",
"includeDetails",
"triggerEvent"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Notification rule identifier"
},
"triggerEvent": {
"type": "string",
"example": "NEW_ACCOUNT_BALANCE",
"description": "Trigger event type",
"enum": [
"NEW_ACCOUNT_BALANCE",
"NEW_TRANSACTIONS",
"BANK_LOGIN_ERROR",
"FOREIGN_MONEY_TRANSFER",
"LOW_ACCOUNT_BALANCE",
"HIGH_TRANSACTION_AMOUNT",
"CATEGORY_CASH_FLOW",
"NEW_TERMS_AND_CONDITIONS"
]
},
"params": {
"type": "object",
"example": {
"accountIds": "1,2,3"
},
"description": "Additional parameters that are specific to the trigger event type. Please refer to the documentation for details.",
"additionalProperties": {
"type": "string"
}
},
"callbackHandle": {
"type": "string",
"example": "handle",
"description": "The string that finAPI includes into the notifications that it sends based on this rule."
},
"includeDetails": {
"description": "Whether the notification messages that will be sent based on this rule contain encrypted detailed data or not",
"example": true,
"type": "boolean"
}
},
"description": "Data of notification rule"
},
"NotificationRuleList": {
"type": "object",
"properties": {
"notificationRules": {
"type": "array",
"description": "List of notification rules",
"items": {
"$ref": "#/definitions/NotificationRule"
}
}
},
"description": "Container for data of multiple notification rules"
},
"NotificationRuleParams": {
"type": "object",
"required": [
"triggerEvent"
],
"properties": {
"triggerEvent": {
"type": "string",
"example": "NEW_ACCOUNT_BALANCE",
"description": "Trigger event type",
"enum": [
"NEW_ACCOUNT_BALANCE",
"NEW_TRANSACTIONS",
"BANK_LOGIN_ERROR",
"FOREIGN_MONEY_TRANSFER",
"LOW_ACCOUNT_BALANCE",
"HIGH_TRANSACTION_AMOUNT",
"CATEGORY_CASH_FLOW",
"NEW_TERMS_AND_CONDITIONS"
]
},
"params": {
"type": "object",
"example": {
"accountIds": "1,2,3"
},
"description": "Additional parameters that are specific to the chosen trigger event type. Please refer to the documentation for details.",
"additionalProperties": {
"type": "string"
}
},
"callbackHandle": {
"type": "string",
"example": "handle",
"description": "An arbitrary string that finAPI will include into the notifications that it sends based on this rule and that you can use to identify the notification in your application. For instance, you could include the identifier of the user that you create this rule for. Maximum allowed length of the string is 512 characters.
Note that for this parameter, you can pass the symbols '/', '=', '%' and '\"' in addition to the symbols that are generally allowed in finAPI (see https://finapi.zendesk.com/hc/en-us/articles/222013148). This was done to enable you to set Base64 encoded strings and JSON structures for the callback handle.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€/=%\"]*"
},
"includeDetails": {
"default": false,
"description": "Whether the notification messages that will be sent based on this rule should contain encrypted detailed data or not",
"example": true,
"type": "boolean"
}
},
"description": "Parameters of notification rule"
},
"PageableBankList": {
"type": "object",
"required": [
"banks",
"paging"
],
"properties": {
"banks": {
"type": "array",
"description": "Banks data",
"items": {
"$ref": "#/definitions/Bank"
}
},
"paging": {
"description": "Information for pagination",
"$ref": "#/definitions/Paging"
}
},
"description": "Container for banks with paging info"
},
"PageableCategoryList": {
"type": "object",
"required": [
"categories",
"paging"
],
"properties": {
"categories": {
"type": "array",
"description": "Categories",
"items": {
"$ref": "#/definitions/Category"
}
},
"paging": {
"description": "Information for pagination",
"$ref": "#/definitions/Paging"
}
},
"description": "Container for categories with paging info"
},
"PageableIbanRuleList": {
"type": "object",
"required": [
"ibanRules",
"paging"
],
"properties": {
"ibanRules": {
"type": "array",
"description": "List of iban rules information",
"items": {
"$ref": "#/definitions/IbanRule"
}
},
"paging": {
"description": "Information for pagination",
"$ref": "#/definitions/Paging"
}
},
"description": "Container for IBAN rule information with paging info"
},
"PageableKeywordRuleList": {
"type": "object",
"required": [
"keywordRules",
"paging"
],
"properties": {
"keywordRules": {
"type": "array",
"description": "List of keyword rules",
"items": {
"$ref": "#/definitions/KeywordRule"
}
},
"paging": {
"description": "Information for pagination",
"$ref": "#/definitions/Paging"
}
},
"description": "Container for keyword rule information with paging info"
},
"PageableLabelList": {
"type": "object",
"required": [
"labels",
"paging"
],
"properties": {
"labels": {
"type": "array",
"description": "Data of labels",
"items": {
"$ref": "#/definitions/Label"
}
},
"paging": {
"description": "Information for pagination",
"$ref": "#/definitions/Paging"
}
},
"description": "Label resources with paging information"
},
"PageablePaymentResources": {
"type": "object",
"required": [
"paging",
"payments"
],
"properties": {
"payments": {
"type": "array",
"description": "List of received account payments",
"items": {
"$ref": "#/definitions/Payment"
}
},
"paging": {
"description": "Information for pagination",
"$ref": "#/definitions/Paging"
}
},
"description": "Payment resources with paging information"
},
"PageableSecurityList": {
"type": "object",
"required": [
"paging",
"securities"
],
"properties": {
"securities": {
"type": "array",
"description": "List of securities",
"items": {
"$ref": "#/definitions/Security"
}
},
"paging": {
"description": "Information for pagination",
"$ref": "#/definitions/Paging"
}
},
"description": "Container for page of securities"
},
"PageableTransactionList": {
"type": "object",
"required": [
"balance",
"income",
"paging",
"spending",
"transactions"
],
"properties": {
"transactions": {
"type": "array",
"description": "Array of transactions (for the requested page)",
"items": {
"$ref": "#/definitions/Transaction"
}
},
"paging": {
"description": "Information for pagination",
"$ref": "#/definitions/Paging"
},
"income": {
"type": "number",
"description": "The total income of all transactions (across all pages)"
},
"spending": {
"type": "number",
"description": "The total spending of all transactions (across all pages)"
},
"balance": {
"type": "number",
"description": "The total sum of all transactions (across all pages)"
}
},
"description": "Container for a page of transactions, with data about the total count of transactions and their balance"
},
"PageableUserInfoList": {
"type": "object",
"required": [
"paging",
"users"
],
"properties": {
"users": {
"type": "array",
"description": "List of users information",
"items": {
"$ref": "#/definitions/UserInfo"
}
},
"paging": {
"description": "Information for pagination",
"$ref": "#/definitions/Paging"
}
},
"description": "Container for users information with paging info"
},
"Paging": {
"type": "object",
"required": [
"page",
"pageCount",
"perPage",
"totalCount"
],
"properties": {
"page": {
"type": "integer",
"format": "int32",
"example": 1,
"description": "Current page number"
},
"perPage": {
"type": "integer",
"format": "int32",
"example": 20,
"description": "Current page size (number of entries in this page)"
},
"pageCount": {
"type": "integer",
"format": "int32",
"example": 10,
"description": "Total number of pages"
},
"totalCount": {
"type": "integer",
"format": "int64",
"example": 200,
"description": "Total number of entries across all pages"
}
},
"description": "Container for pagination information"
},
"PasswordChangingResource": {
"type": "object",
"required": [
"passwordChangeToken",
"userId"
],
"properties": {
"userId": {
"type": "string",
"example": "username",
"description": "User identifier"
},
"userEmail": {
"type": "string",
"example": "[email protected]",
"description": "User's email, encrypted. Decrypt with your data decryption key. If the user has no email set, then this field will be null."
},
"passwordChangeToken": {
"type": "string",
"example": "EnCRyPTEDPassWordCHAnGEToKen==",
"description": "Encrypted password change token. Decrypt this token with your data decryption key, and pass the decrypted token to the /users/executePasswordChange service in order to set a new password for the user."
}
},
"description": "Password changing details"
},
"Payment": {
"type": "object",
"required": [
"accountId",
"amount",
"id",
"orderCount",
"requestDate",
"status",
"type"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Payment identifier"
},
"accountId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier of the account to which this payment relates"
},
"requestDate": {
"type": "string",
"example": "2019-01-01 00:00:00.000",
"description": "Time of when this payment was requested, in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)"
},
"executionDate": {
"type": "string",
"example": "2019-01-01 00:00:00.000",
"description": "Time of when this payment was executed, in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)"
},
"type": {
"type": "string",
"example": "MONEY_TRANSFER",
"description": "Payment type",
"enum": [
"MONEY_TRANSFER",
"DIRECT_DEBIT"
]
},
"status": {
"type": "string",
"example": "PENDING",
"description": "Current payment status:
• PENDING: means that this payment has been requested, but not yet executed.
• SUCCESSFUL: means that this payment has been successfully executed.
• NOT_SUCCESSFUL: means that this payment could not be executed successfully.
• DISCARDED: means that this payment was discarded because another payment was requested for the same account before this payment was executed.",
"enum": [
"PENDING",
"SUCCESSFUL",
"NOT_SUCCESSFUL",
"DISCARDED"
]
},
"bankMessage": {
"type": "string",
"description": "Contains the bank's response to the execution of this payment. This field is not set until the payment gets executed. Note that even after the execution of the payment, the field might still not be set, if the bank did not send any response message."
},
"amount": {
"type": "number",
"example": 99.99,
"description": "Total money amount of the payment order(s), as absolute value"
},
"orderCount": {
"type": "integer",
"format": "int32",
"example": 1,
"description": "Total count of orders included in this payment"
}
},
"description": "Container for a payment's data"
},
"PaymentExecutionResponse": {
"type": "object",
"required": [
"paymentId"
],
"properties": {
"successMessage": {
"type": "string",
"example": "Auftrag ausgeführt.",
"description": "Technical message from the bank server, confirming the success of the request. Typically, you would not want to present this message to the user. Note that this field may not be set. However if it is not set, it does not necessarily mean that there was an error in processing the request."
},
"warnMessage": {
"type": "string",
"example": "Es liegen Warnungen vor.",
"description": "In some cases, a bank server may accept the requested order, but return a warn message. This message may be of technical nature, but could also be of interest to the user."
},
"paymentId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Payment identifier. Can be used to retrieve the status of the payment (see 'Get payments' service)."
}
},
"description": "Bank server's response to Money Transfer / Direct Debit execution"
},
"PaypalTransactionData": {
"type": "object",
"properties": {
"invoiceNumber": {
"type": "string",
"example": "INV2-KXVU-7Z64-DT6W-MG2X",
"description": "Invoice Number.
NOTE: This field is deprecated as the bank with blz 'PAYPAL' is no longer supported. Do not use this field, as it will be removed at some point."
},
"fee": {
"type": "number",
"example": -0.99,
"description": "Fee value.
NOTE: This field is deprecated as the bank with blz 'PAYPAL' is no longer supported. Do not use this field, as it will be removed at some point."
},
"net": {
"type": "number",
"example": 9.99,
"description": "Net value.
NOTE: This field is deprecated as the bank with blz 'PAYPAL' is no longer supported. Do not use this field, as it will be removed at some point."
},
"auctionSite": {
"type": "string",
"example": "eBay",
"description": "Auction Site.
NOTE: This field is deprecated as the bank with blz 'PAYPAL' is no longer supported. Do not use this field, as it will be removed at some point."
}
},
"description": "Additional, PayPal-specific transaction data. This field is only set for transactions that belong to an account of the 'PayPal' bank (BLZ 'PAYPAL')."
},
"RequestPasswordChangeParams": {
"type": "object",
"required": [
"userId"
],
"properties": {
"userId": {
"type": "string",
"example": "username",
"description": "User identifier",
"pattern": "[a-zA-Z0-9\\-_\\.\\+@]*"
}
},
"description": "Request password change parameters"
},
"RequestSepaDirectDebitParams": {
"type": "object",
"required": [
"accountId",
"directDebitType",
"directDebits",
"executionDate",
"sequenceType"
],
"properties": {
"accountId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier of the bank account to which you want to transfer the money."
},
"bankingPin": {
"type": "string",
"example": "123456",
"description": "Online banking PIN. Any symbols are allowed. Max length: 170. If a PIN is stored in the bank connection, then this field may remain unset. If finAPI's web form is not required and the field is set though then it will always be used (even if there is some other PIN stored in the bank connection). If you want the user to enter a PIN in finAPI's web form even when a PIN is stored, then just set the field to any value, so that the service recognizes that you wish to use the web form flow."
},
"storePin": {
"default": false,
"description": "Whether to store the PIN. If the PIN is stored, it is not required to pass the PIN again when executing SEPA orders. Default value is 'false'.
NOTES:
- before you set this field to true, please regard the 'pinsAreVolatile' flag of the bank connection that the account belongs to;
- this field is ignored in case when the user will need to use finAPI's 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).",
"example": true,
"type": "boolean"
},
"twoStepProcedureId": {
"type": "string",
"example": "955",
"description": "The bank-given ID of the two-step-procedure that should be used for the order. For a list of available two-step-procedures, see the corresponding bank connection (GET /bankConnections). If this field is not set, then the bank connection's default two-step-procedure will be used. Note that in this case, when the bank connection has no default two-step-procedure set, then the response of the service depends on whether you need to use finAPI's web form or not. If you need to use the web form, the user will be prompted to select the two-step-procedure within the web form. If you don't need to use the web form, then the service will return an error (passing a value for this field is required in this case)."
},
"directDebitType": {
"type": "string",
"example": "B2B",
"description": "Type of the direct debit; either BASIC or B2B (Business-To-Business). Please note that an account which supports the basic type must not necessarily support B2B (or vice versa). Check the source account's 'supportedOrders' field to find out which types of direct debit it supports.
",
"enum": [
"B2B",
"BASIC"
]
},
"sequenceType": {
"type": "string",
"example": "OOFF",
"description": "Sequence type of the direct debit. Possible values:
• OOFF - means that this is a one-time direct debit order
• FRST - means that this is the first in a row of multiple direct debit orders
• RCUR - means that this is one (but not the first or final) within a row of multiple direct debit orders
• FNAL - means that this is the final in a row of multiple direct debit orders
",
"enum": [
"OOFF",
"FRST",
"RCUR",
"FNAL"
]
},
"executionDate": {
"type": "string",
"example": "2018-01-01",
"description": "Execution date for the direct debit(s), in the format 'YYYY-MM-DD'."
},
"singleBooking": {
"default": false,
"description": "This field is only regarded when you pass multiple orders. It determines whether the orders should be processed by the bank as one collective booking (in case of 'false'), or as single bookings (in case of 'true'). Default value is 'false'.",
"example": false,
"type": "boolean"
},
"directDebits": {
"type": "array",
"description": "List of the direct debits that you want to execute (may contain at most 15000 items). Please check the account's 'supportedOrders' field to find out whether you can pass multiple direct debits or just one.",
"items": {
"$ref": "#/definitions/SingleDirectDebitData"
}
}
},
"description": "Parameters for a single or collective SEPA direct debit order request"
},
"RequestSepaMoneyTransferParams": {
"type": "object",
"required": [
"accountId",
"amount"
],
"properties": {
"recipientName": {
"type": "string",
"example": "Max Mustermann",
"description": "Name of the recipient. Note: Neither finAPI nor the involved bank servers are guaranteed to validate the recipient name. Even if the recipient name does not depict the actual registered account holder of the specified recipient account, the money transfer request might still be successful. This field is optional only when you pass a clearing account as the recipient. Otherwise, this field is required."
},
"recipientIban": {
"type": "string",
"example": "DE13700800000061110500",
"description": "IBAN of the recipient's account. This field is optional only when you pass a clearing account as the recipient. Otherwise, this field is required."
},
"recipientBic": {
"type": "string",
"example": "DRESDEFF700",
"description": "BIC of the recipient's account. Note: This field is optional when you pass a clearing account as the recipient or if the bank connection of the account that you want to transfer money from supports the IBAN-Only money transfer. You can find this out via GET /bankConnections/. Also note that when a BIC is given, then this BIC will be used for the money transfer request independent of whether it is required or not (unless you pass a clearing account, in which case this field will always be ignored)."
},
"clearingAccountId": {
"type": "string",
"example": "BA-TUYEF7D24CGK6",
"description": "Identifier of a clearing account. If this field is set, then the fields 'recipientName', 'recipientIban' and 'recipientBic' will be ignored and the recipient account will be the specified clearing account."
},
"amount": {
"type": "number",
"example": 99.99,
"description": "The amount to transfer. Must be a positive decimal number with at most two decimal places (e.g. 99.99)"
},
"purpose": {
"type": "string",
"example": "Test Payment",
"description": "The purpose of the transfer transaction"
},
"sepaPurposeCode": {
"type": "string",
"example": "OTHR",
"description": "SEPA purpose code, according to ISO 20022, external codes set."
},
"accountId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier of the bank account that you want to transfer money from"
},
"bankingPin": {
"type": "string",
"example": "123456",
"description": "Online banking PIN. Any symbols are allowed. Max length: 170. If a PIN is stored in the bank connection, then this field may remain unset. If finAPI's web form is not required and the field is set though then it will always be used (even if there is some other PIN stored in the bank connection). If you want the user to enter a PIN in finAPI's web form even when a PIN is stored, then just set the field to any value, so that the service recognizes that you wish to use the web form flow."
},
"storePin": {
"default": false,
"description": "Whether to store the PIN. If the PIN is stored, it is not required to pass the PIN again when executing SEPA orders. Default value is 'false'.
NOTES:
- before you set this field to true, please regard the 'pinsAreVolatile' flag of the bank connection that the account belongs to;
- this field is ignored in case when the user will need to use finAPI's 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).",
"example": true,
"type": "boolean"
},
"twoStepProcedureId": {
"type": "string",
"example": "955",
"description": "The bank-given ID of the two-step-procedure that should be used for the order. For a list of available two-step-procedures, see the corresponding bank connection (GET /bankConnections). If this field is not set, then the bank connection's default two-step-procedure will be used. Note that in this case, when the bank connection has no default two-step-procedure set, then the response of the service depends on whether you need to use finAPI's web form or not. If you need to use the web form, the user will be prompted to select the two-step-procedure within the web form. If you don't need to use the web form, then the service will return an error (passing a value for this field is required in this case)."
},
"challengeResponse": {
"type": "string",
"example": "0123",
"description": "Challenge response. This field should be set only when the previous attempt to request a SEPA money transfer 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. Please note that in case of using finAPI's web form you have to leave this field unset and the application will automatically recognize that the user has to input challenge response and then a web form will be shown to the user."
},
"executionDate": {
"type": "string",
"example": "2018-01-01",
"description": "Execution date for the money transfer(s), in the format 'YYYY-MM-DD'. If not specified, then the current date will be used."
},
"singleBooking": {
"default": false,
"description": "This field is only regarded when you pass multiple orders. It determines whether the orders should be processed by the bank as one collective booking (in case of 'false'), or as single bookings (in case of 'true'). Default value is 'false'.",
"example": false,
"type": "boolean"
},
"additionalMoneyTransfers": {
"type": "array",
"description": "In case that you want to submit not just a single money transfer, but do a collective money transfer, use this field to pass a list of additional money transfer orders. The service will then pass a collective money transfer request to the bank, including both the money transfer specified on the top-level, as well as all money transfers specified in this list. The maximum count of money transfers that you can pass (in total) is 15000. Note that you should check the account's 'supportedOrders' field to find out whether or not it is supporting collective money transfers.",
"items": {
"$ref": "#/definitions/SingleMoneyTransferRecipientData"
}
}
},
"description": "Parameters for a single or collective SEPA money transfer order request"
},
"Security": {
"type": "object",
"required": [
"accountId",
"id"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier. 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."
},
"accountId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Security account identifier"
},
"name": {
"type": "string",
"example": "Wertapapierbezeichnung",
"description": "Name"
},
"isin": {
"type": "string",
"example": "DE0008404005",
"description": "ISIN"
},
"wkn": {
"type": "string",
"example": "840400",
"description": "WKN"
},
"quote": {
"type": "number",
"example": 99.999999,
"description": "Quote"
},
"quoteCurrency": {
"type": "string",
"example": "EUR",
"description": "Currency of quote"
},
"quoteType": {
"type": "string",
"example": "ACTU",
"description": "Type of quote. 'PERC' if quote is a percentage value, 'ACTU' if quote is the actual amount",
"enum": [
"ACTU",
"PERC"
]
},
"quoteDate": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Quote date in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
},
"quantityNominal": {
"type": "number",
"example": 99.999999,
"description": "Value of quantity or nominal"
},
"quantityNominalType": {
"type": "string",
"example": "UNIT",
"description": "Type of quantity or nominal value. 'UNIT' if value is a quantity, 'FAMT' if value is the nominal amount",
"enum": [
"UNIT",
"FAMT"
]
},
"marketValue": {
"type": "number",
"example": 99.999999,
"description": "Market value"
},
"marketValueCurrency": {
"type": "string",
"example": "EUR",
"description": "Currency of market value"
},
"entryQuote": {
"type": "number",
"example": 99.999999,
"description": "Entry quote"
},
"entryQuoteCurrency": {
"type": "string",
"example": "EUR",
"description": "Currency of entry quote"
},
"profitOrLoss": {
"type": "number",
"example": 99.999999,
"description": "Current profit or loss"
}
},
"description": "Container for a security position's data"
},
"SecurityList": {
"type": "object",
"required": [
"securities"
],
"properties": {
"securities": {
"type": "array",
"description": "List of securities",
"items": {
"$ref": "#/definitions/Security"
}
}
},
"description": "Container for securities resources"
},
"SingleDirectDebitData": {
"type": "object",
"required": [
"amount",
"debitorIban",
"debitorName",
"mandateDate",
"mandateId"
],
"properties": {
"debitorName": {
"type": "string",
"example": "Debitor",
"description": "Name of the debitor. Note: Neither finAPI nor the involved bank servers are guaranteed to validate the debitor name. Even if the debitor name does not depict the actual registered account holder of the specified debitor account, the direct debit request might still be successful."
},
"debitorIban": {
"type": "string",
"example": "DE13700800000061110500",
"description": "IBAN of the debitor's account"
},
"debitorBic": {
"type": "string",
"example": "DRESDEFF700",
"description": "BIC of the debitor's account. Note: This field is optional if - and only if - the bank connection of the account that you want to transfer money to supports the IBAN-Only direct debit. You can find this out via GET /bankConnections/. Also note that when a BIC is given, then this BIC will be used for the direct debit request independent of whether it is required or not."
},
"amount": {
"type": "number",
"example": 99.99,
"description": "The amount to transfer. Must be a positive decimal number with at most two decimal places (e.g. 99.99)"
},
"purpose": {
"type": "string",
"example": "Test Payment",
"description": "The purpose of the transfer transaction"
},
"sepaPurposeCode": {
"type": "string",
"example": "OTHR",
"description": "SEPA purpose code, according to ISO 20022, external codes set."
},
"mandateId": {
"type": "string",
"example": "1",
"description": "Mandate ID that this direct debit order is based on."
},
"mandateDate": {
"type": "string",
"example": "2018-01-01",
"description": "Date of the mandate that this direct debit order is based on, in the format 'YYYY-MM-DD'"
},
"creditorId": {
"type": "string",
"example": "Creditor",
"description": "Creditor ID of the source account's holder"
},
"endToEndId": {
"type": "string",
"example": "001100550526",
"description": "End-To-End ID for the transfer transaction"
}
},
"description": "Data for a single direct debit"
},
"SingleMoneyTransferRecipientData": {
"type": "object",
"required": [
"amount"
],
"properties": {
"recipientName": {
"type": "string",
"example": "Max Mustermann",
"description": "Name of the recipient. Note: Neither finAPI nor the involved bank servers are guaranteed to validate the recipient name. Even if the recipient name does not depict the actual registered account holder of the specified recipient account, the money transfer request might still be successful. This field is optional only when you pass a clearing account as the recipient. Otherwise, this field is required."
},
"recipientIban": {
"type": "string",
"example": "DE13700800000061110500",
"description": "IBAN of the recipient's account. This field is optional only when you pass a clearing account as the recipient. Otherwise, this field is required."
},
"recipientBic": {
"type": "string",
"example": "DRESDEFF700",
"description": "BIC of the recipient's account. Note: This field is optional when you pass a clearing account as the recipient or if the bank connection of the account that you want to transfer money from supports the IBAN-Only money transfer. You can find this out via GET /bankConnections/. Also note that when a BIC is given, then this BIC will be used for the money transfer request independent of whether it is required or not (unless you pass a clearing account, in which case this field will always be ignored)."
},
"clearingAccountId": {
"type": "string",
"example": "BA-TUYEF7D24CGK6",
"description": "Identifier of a clearing account. If this field is set, then the fields 'recipientName', 'recipientIban' and 'recipientBic' will be ignored and the recipient account will be the specified clearing account."
},
"amount": {
"type": "number",
"example": 99.99,
"description": "The amount to transfer. Must be a positive decimal number with at most two decimal places (e.g. 99.99)"
},
"purpose": {
"type": "string",
"example": "Test Payment",
"description": "The purpose of the transfer transaction"
},
"sepaPurposeCode": {
"type": "string",
"example": "OTHR",
"description": "SEPA purpose code, according to ISO 20022, external codes set."
}
},
"description": "Recipient data for a single money transfer order"
},
"SplitTransactionsParams": {
"type": "object",
"required": [
"subTransactions"
],
"properties": {
"subTransactions": {
"type": "array",
"description": "List of sub-transactions",
"items": {
"$ref": "#/definitions/SubTransactionParams"
}
}
},
"description": "Set of logical sub-transactions that a transaction should get split into"
},
"SubTransactionParams": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"example": -99.99,
"description": "Amount"
},
"categoryId": {
"type": "integer",
"format": "int64",
"example": 378,
"description": "Category identifier. If not specified, the original transaction's category will be applied. If you explicitly want the sub-transaction to have no category, then pass this field with value '0' (zero)."
},
"purpose": {
"type": "string",
"example": "Restaurantbesuch",
"description": "Purpose. Maximum length is 2000. If not specified, the original transaction's value will be applied.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"counterpart": {
"type": "string",
"example": "TueV Bayern",
"description": "Counterpart. Maximum length is 80. If not specified, the original transaction's value will be applied.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"counterpartAccountNumber": {
"type": "string",
"example": "61110500",
"description": "Counterpart account number. If not specified, the original transaction's value will be applied.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"counterpartIban": {
"type": "string",
"example": "DE13700800000061110500",
"description": "Counterpart IBAN. If not specified, the original transaction's value will be applied."
},
"counterpartBic": {
"type": "string",
"example": "DRESDEFF700",
"description": "Counterpart BIC. If not specified, the original transaction's value will be applied."
},
"counterpartBlz": {
"type": "string",
"example": "70080000",
"description": "Counterpart BLZ. If not specified, the original transaction's value will be applied."
},
"labelIds": {
"type": "array",
"example": [
1,
2,
3
],
"description": "List of connected labels. Note that when this field is not specified, then the labels of the original transaction will NOT get applied to the sub-transaction. Instead, the sub-transaction will have no labels assigned to it.",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"description": "Data of a sub-transaction"
},
"TrainCategorizationData": {
"type": "object",
"required": [
"categoryId",
"transactionData"
],
"properties": {
"transactionData": {
"type": "array",
"description": "Set of transaction data (at most 100 transactions at once)",
"items": {
"$ref": "#/definitions/TrainCategorizationTransactionData"
}
},
"categoryId": {
"type": "integer",
"format": "int64",
"example": 378,
"description": "Category identifier"
}
},
"description": "Sample data to train categorization"
},
"TrainCategorizationTransactionData": {
"type": "object",
"required": [
"accountTypeId",
"amount"
],
"properties": {
"accountTypeId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Identifier of account type.
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
",
"minimum": 1.0,
"maximum": 7.0
},
"amount": {
"type": "number",
"example": -99.99,
"description": "Amount"
},
"purpose": {
"type": "string",
"example": "Restaurantbesuch",
"description": "Purpose. Any symbols are allowed. Maximum length is 2000. Default value: null."
},
"counterpart": {
"type": "string",
"example": "Bar Centrale",
"description": "Counterpart. Any symbols are allowed. Maximum length is 80. Default value: null."
},
"counterpartIban": {
"type": "string",
"example": "DE13700800000061110500",
"description": "Counterpart IBAN. Default value: null."
},
"counterpartAccountNumber": {
"type": "string",
"example": "61110500",
"description": "Counterpart account number. Default value: null."
},
"counterpartBlz": {
"type": "string",
"example": "70080000",
"description": "Counterpart BLZ. Default value: null."
},
"counterpartBic": {
"type": "string",
"example": "DRESDEFF700",
"description": "Counterpart BIC. Default value: null."
},
"mcCode": {
"type": "string",
"example": "5542",
"description": "Merchant category code (for credit card transactions only). Default value: null. NOTE: This field is currently not regarded."
}
},
"description": "Transaction data for categorization training"
},
"Transaction": {
"type": "object",
"required": [
"accountId",
"amount",
"bankBookingDate",
"finapiBookingDate",
"id",
"importDate",
"isAdjustingEntry",
"isNew",
"isPotentialDuplicate",
"valueDate"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Transaction identifier"
},
"parentId": {
"type": "integer",
"format": "int64",
"example": 2,
"description": "Parent transaction identifier"
},
"accountId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Account identifier"
},
"valueDate": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Value date in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
},
"bankBookingDate": {
"type": "string",
"example": "2018-01-01 00.00.00.000",
"description": "Bank booking date in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
},
"finapiBookingDate": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "finAPI Booking date in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time). NOTE: In some cases, banks may deliver transactions that are booked in future, but already included in the current account balance. To keep the account balance consistent with the set of transactions, such \"future transactions\" will be imported with their finapiBookingDate set to the current date (i.e.: date of import). The finapiBookingDate will automatically get adjusted towards the bankBookingDate each time the associated bank account is updated. Example: A transaction is imported on July, 3rd, with a bank reported booking date of July, 6th. The transaction will be imported with its finapiBookingDate set to July, 3rd. Then, on July 4th, the associated account is updated. During this update, the transaction's finapiBookingDate will be automatically adjusted to July 4th. This adjustment of the finapiBookingDate takes place on each update until the bank account is updated on July 6th or later, in which case the transaction's finapiBookingDate will be adjusted to its final value, July 6th.
The finapiBookingDate is the date that is used by the finAPI PFM services. E.g. when you calculate the spendings of an account for the current month, and have a transaction with finapiBookingDate in the current month but bankBookingDate at the beginning of the next month, then this transaction is included in the calculations (as the bank has this transaction's amount included in the current account balance as well)."
},
"amount": {
"type": "number",
"example": -99.99,
"description": "Transaction amount"
},
"purpose": {
"type": "string",
"example": "Restaurantbesuch",
"description": "Transaction purpose. Maximum length: 2000"
},
"counterpartName": {
"type": "string",
"example": "Bar Centrale",
"description": "Counterpart name. Maximum length: 80"
},
"counterpartAccountNumber": {
"type": "string",
"example": "0061110500",
"description": "Counterpart account number"
},
"counterpartIban": {
"type": "string",
"example": "DE13700800000061110500",
"description": "Counterpart IBAN"
},
"counterpartBlz": {
"type": "string",
"example": "70080000",
"description": "Counterpart BLZ"
},
"counterpartBic": {
"type": "string",
"example": "DRESDEFF700",
"description": "Counterpart BIC"
},
"counterpartBankName": {
"type": "string",
"example": "Commerzbank vormals Dresdner Bank",
"description": "Counterpart Bank name"
},
"counterpartMandateReference": {
"type": "string",
"example": "MR123",
"description": "The mandate reference of the counterpart"
},
"counterpartCustomerReference": {
"type": "string",
"example": "CUR123",
"description": "The customer reference of the counterpart"
},
"counterpartCreditorId": {
"type": "string",
"example": "CRI123",
"description": "The creditor ID of the counterpart. Exists only for SEPA direct debit transactions (\"Lastschrift\")."
},
"counterpartDebitorId": {
"type": "string",
"example": "CRI098",
"description": "The originator's identification code. Exists only for SEPA money transfer transactions (\"Überweisung\")."
},
"type": {
"type": "string",
"example": "Überweisungsauftrag",
"description": "Transaction type, according to the bank. If set, this will contain a German term that you can display to the user. Some examples of common values are: \"Lastschrift\", \"Auslandsüberweisung\", \"Gebühren\", \"Zinsen\". The maximum possible length of this field is 255 characters."
},
"typeCodeZka": {
"type": "string",
"example": "999",
"description": "ZKA business transaction code which relates to the transaction's type. Possible values range from 1 through 999. If no information about the ZKA type code is available, then this field will be null."
},
"typeCodeSwift": {
"type": "string",
"example": "RAPRDE51",
"description": "SWIFT transaction type code. If no information about the SWIFT code is available, then this field will be null."
},
"sepaPurposeCode": {
"type": "string",
"example": "OTHR",
"description": "SEPA purpose code, according to ISO 20022"
},
"primanota": {
"type": "string",
"example": "Primanota",
"description": "Transaction primanota (bank side identification number)"
},
"category": {
"description": "Transaction category, if any is assigned. Note: Recently imported transactions that have currently no category assigned might still get categorized by the background categorization process. To check the status of the background categorization, see GET /bankConnections. Manual category assignments to a transaction will remove the transaction from the background categorization process (i.e. the background categorization process will never overwrite a manual category assignment).",
"$ref": "#/definitions/Category"
},
"labels": {
"type": "array",
"description": "Array of assigned labels",
"items": {
"$ref": "#/definitions/Label"
}
},
"isPotentialDuplicate": {
"description": "While finAPI uses a well-elaborated algorithm for uniquely identifying transactions, there is still the possibility that during an account update, a transaction that was imported previously may be imported a second time as a new transaction. For example, this can happen if some transaction data changes on the bank server side. However, finAPI also includes an algorithm of identifying such \"potential duplicate\" transactions. If this field is set to true, it means that finAPI detected a similar transaction that might actually be the same. It is recommended to communicate this information to the end user, and give him an option to delete the transaction in case he confirms that it really is a duplicate.",
"example": false,
"type": "boolean"
},
"isAdjustingEntry": {
"description": "Indicating whether this transaction is an adjusting entry ('Zwischensaldo').
Adjusting entries do not originate from the bank, but are added by finAPI during an account update when the bank reported account balance does not add up to the set of transactions that finAPI receives for the account. In this case, the adjusting entry will fix the deviation between the balance and the received transactions so that both adds up again.
Possible causes for such deviations are:
- Inconsistencies in how the bank calculates the balance, for instance when not yet booked transactions are already included in the balance, but not included in the set of transactions
- Gaps in the transaction history that finAPI receives, for instance because the account has not been updated for a while and older transactions are no longer available",
"example": false,
"type": "boolean"
},
"isNew": {
"description": "Indicating whether this transaction is 'new' or not. Any newly imported transaction will have this flag initially set to true. How you use this field is up to your interpretation. For example, you might want to set it to false once a user has clicked on/seen the transaction. You can change this flag to 'false' with the PATCH method.",
"example": true,
"type": "boolean"
},
"importDate": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Date of transaction import, in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
},
"children": {
"type": "array",
"example": [
1,
2,
3
],
"description": "Sub-transactions identifiers (if this transaction is split)",
"items": {
"type": "integer",
"format": "int64"
}
},
"paypalData": {
"description": "Additional, PayPal-specific transaction data. This field is only set for transactions that belong to an account of the 'PayPal' bank (BLZ 'PAYPAL').
NOTE: This field is deprecated as the bank with blz 'PAYPAL' is no longer supported. Do not use this field, as it will be removed at some point.",
"$ref": "#/definitions/PaypalTransactionData"
},
"endToEndReference": {
"type": "string",
"example": "001100550526",
"description": "End-To-End reference"
},
"compensationAmount": {
"type": "number",
"example": -1.11,
"description": "Compensation Amount. Sum of reimbursement of out-of-pocket expenses plus processing brokerage in case of a national return / refund debit as well as an optional interest equalisation. Exists predominantly for SEPA direct debit returns."
},
"originalAmount": {
"type": "number",
"example": -9.99,
"description": "Original Amount of the original direct debit. Exists predominantly for SEPA direct debit returns."
},
"differentDebitor": {
"type": "string",
"example": "DIFD70204",
"description": "Payer's/debtor's reference party (in the case of a credit transfer) or payee's/creditor's reference party (in the case of a direct debit)"
},
"differentCreditor": {
"type": "string",
"example": "DIFC98450",
"description": "Payee's/creditor's reference party (in the case of a credit transfer) or payer's/debtor's reference party (in the case of a direct debit)"
}
},
"description": "Container for a transaction's data"
},
"TransactionList": {
"type": "object",
"required": [
"transactions"
],
"properties": {
"transactions": {
"type": "array",
"description": "Array of transactions",
"items": {
"$ref": "#/definitions/Transaction"
}
}
},
"description": "Container for data of multiple transactions"
},
"TriggerCategorizationParams": {
"type": "object",
"properties": {
"bankConnectionIds": {
"type": "array",
"example": [
1,
2,
3
],
"description": "List of identifiers of the bank connections that you want to trigger categorization for. Leaving the list unset or empty will trigger categorization for all of the user's bank connections. Please note that if there are no bank connections, then the service will return with HTTP code 422.",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"description": "Trigger categorization parameters"
},
"TwoStepProcedure": {
"type": "object",
"required": [
"implicitExecute",
"procedureId",
"procedureName"
],
"properties": {
"procedureId": {
"type": "string",
"example": "955",
"description": "Bank-given ID of the procedure"
},
"procedureName": {
"type": "string",
"example": "mobileTAN",
"description": "Bank-given name of the procedure"
},
"procedureChallengeType": {
"type": "string",
"example": "TEXT",
"description": "The challenge type of the procedure. Possible values are:
• TEXT - the challenge will be a text that contains instructions for the user on how to retrieve the TAN.
• PHOTO - the challenge will contain a BASE-64 string depicting a photo (or any kind of QR-code-like data) that must be shown to the user.
• FLICKER_CODE - the challenge will contain a BASE-64 string depicting a flicker code animation that must be shown to the user.
Note that this challenge type information does not originate from the bank server, but is determined by finAPI internally. There is no guarantee that the determined challenge type is correct. Note also that this field may not be set, meaning that finAPI could not determine the challenge type of the procedure.
For further information on how to deal with the challenges, please see this article on our Dev Portal."
},
"implicitExecute": {
"description": "If 'true', then requesting a SEPA order with this procedure will implicitly trigger the execution of the order. For example, if you do a money transfer with this procedure, then calling the /requestSepaMoneyTransfer service will immediately execute the order (a call to /executeSepaMoneyTransfer will not be necessary). On the other hand, if this flag is 'false', then doing a money transfer with this procedure will require you to first call /requestSepaMoneyTransfer, and then call /executeSepaMoneyTransfer.",
"example": false,
"type": "boolean"
}
},
"description": "Two-step-procedure for a communication with a bank server, e.g. for doing a money transfer"
},
"UpdateBankConnectionParams": {
"type": "object",
"required": [
"bankConnectionId"
],
"properties": {
"bankConnectionId": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Bank connection identifier"
},
"bankingPin": {
"type": "string",
"example": "123456",
"description": "Online banking PIN. Any symbols are allowed. Max length: 170. If a PIN is stored in the bank connection, then this field may remain unset. If finAPI's web form is not required and the field is set though then it will always be used (even if there is some other PIN stored in the bank connection). If you want the user to enter a PIN in finAPI's web form even when a PIN is stored, then just set the field to any value, so that the service recognizes that you wish to use the web form flow."
},
"storePin": {
"default": false,
"description": "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 finAPI's 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).",
"example": true,
"type": "boolean"
},
"importNewAccounts": {
"default": false,
"description": "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.",
"example": false,
"type": "boolean"
},
"skipPositionsDownload": {
"default": false,
"description": "Whether to skip the download of transactions and securities or not. If set to true, then finAPI 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 finAPI 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 finAPI's 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.
",
"example": false,
"type": "boolean"
},
"loadOwnerData": {
"default": false,
"description": "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.",
"example": false,
"type": "boolean"
},
"challengeResponse": {
"type": "string",
"example": "0123",
"description": "Challenge response. This field should be set only when the previous attempt of update 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 finAPI's web form flow, finAPI will automatically deal with getting the challenge response from the user via the web form."
}
},
"description": "Container for bank connection update parameters"
},
"UpdateMultipleTransactionsParams": {
"type": "object",
"properties": {
"isNew": {
"description": "Whether this transactions should be flagged as 'new' or not. Any newly imported transaction will have this flag initially set to true. How you use this field is up to your interpretation. For example, you might want to set it to false once a user has clicked on/seen the transaction.",
"example": false,
"type": "boolean"
},
"isPotentialDuplicate": {
"description": "You can set this field only to 'false'. finAPI marks transactions as a potential duplicates when its internal duplicate detection algorithm is signaling so. Transactions that are flagged as duplicates can be deleted by the user. To prevent the user from deleting original transactions, which might lead to incorrect balances, it is not possible to manually set this flag to 'true'.",
"example": false,
"type": "boolean"
},
"categoryId": {
"type": "integer",
"format": "int64",
"example": 378,
"description": "Identifier of the new category to apply to the transaction. When updating the transaction's category, the category's fields 'id', 'name', 'parentId', 'parentName', and 'isCustom' will all get updated. To clear the category for the transaction, the categoryId field must be passed with value 0."
},
"trainCategorization": {
"default": true,
"description": "This field is only regarded when the field 'categoryId' is set. It controls whether finAPI's categorization system should learn from the given categorization(s). If set to 'true', then the user's categorization rules will be updated so that similar transactions will get categorized accordingly in future. If set to 'false', then the service will simply change the category of the given transaction(s), without updating the user's categorization rules. The field defaults to 'true' if not specified.",
"example": true,
"type": "boolean"
},
"labelIds": {
"type": "array",
"example": [
1,
2,
3
],
"description": "Identifiers of labels to apply to the transaction. To clear transactions' labels, pass an empty array of identifiers: '[]'",
"items": {
"type": "integer",
"format": "int64"
}
},
"ids": {
"type": "array",
"example": [
1,
2,
3
],
"description": "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 100.",
"items": {
"type": "integer",
"format": "int64"
}
},
"accountIds": {
"type": "array",
"example": [
1,
2,
3
],
"description": "A comma-separated list of account identifiers. If specified, then only transactions whose account's identifier is included in this list will be regarded.",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"description": "Update specific transactions parameters"
},
"UpdateResult": {
"type": "object",
"required": [
"result",
"timestamp"
],
"properties": {
"result": {
"type": "string",
"example": "INTERNAL_SERVER_ERROR",
"description": "Note that 'OK' just means that finAPI could successfully connect and log in to the bank server. However, it does not necessarily mean that all accounts could be updated successfully. For the latter, please refer to the 'status' field of the Account resource.",
"enum": [
"OK",
"BANK_SERVER_REJECTION",
"INTERNAL_SERVER_ERROR"
]
},
"errorMessage": {
"type": "string",
"example": "Internal server error",
"description": "In case the update result is not OK, this field may contain an error message with details about why the update failed (it is not guaranteed that a message is available though). In case the update result is OK, the field will always be null."
},
"errorType": {
"type": "string",
"example": "TECHNICAL",
"description": "In case the update result is not OK, this field contains the type of the error that occurred. BUSINESS means that the bank server responded with a non-technical error message for the user. TECHNICAL means that some internal error has occurred in finAPI or at the bank server.",
"enum": [
"BUSINESS",
"TECHNICAL"
]
},
"timestamp": {
"type": "string",
"example": "2018-01-01 00:00:00.000",
"description": "Time of the update. The value is returned in the format 'YYYY-MM-DD HH:MM:SS.SSS' (german time)."
}
},
"description": "Container for a status of bank connection update"
},
"UpdateTransactionsParams": {
"type": "object",
"properties": {
"isNew": {
"description": "Whether this transactions should be flagged as 'new' or not. Any newly imported transaction will have this flag initially set to true. How you use this field is up to your interpretation. For example, you might want to set it to false once a user has clicked on/seen the transaction.",
"example": false,
"type": "boolean"
},
"isPotentialDuplicate": {
"description": "You can set this field only to 'false'. finAPI marks transactions as a potential duplicates when its internal duplicate detection algorithm is signaling so. Transactions that are flagged as duplicates can be deleted by the user. To prevent the user from deleting original transactions, which might lead to incorrect balances, it is not possible to manually set this flag to 'true'.",
"example": false,
"type": "boolean"
},
"categoryId": {
"type": "integer",
"format": "int64",
"example": 378,
"description": "Identifier of the new category to apply to the transaction. When updating the transaction's category, the category's fields 'id', 'name', 'parentId', 'parentName', and 'isCustom' will all get updated. To clear the category for the transaction, the categoryId field must be passed with value 0."
},
"trainCategorization": {
"default": true,
"description": "This field is only regarded when the field 'categoryId' is set. It controls whether finAPI's categorization system should learn from the given categorization(s). If set to 'true', then the user's categorization rules will be updated so that similar transactions will get categorized accordingly in future. If set to 'false', then the service will simply change the category of the given transaction(s), without updating the user's categorization rules. The field defaults to 'true' if not specified.",
"example": true,
"type": "boolean"
},
"labelIds": {
"type": "array",
"example": [
1,
2,
3
],
"description": "Identifiers of labels to apply to the transaction. To clear transactions' labels, pass an empty array of identifiers: '[]'",
"items": {
"type": "integer",
"format": "int64"
}
}
},
"description": "Update transactions parameters"
},
"User": {
"type": "object",
"required": [
"id",
"isAutoUpdateEnabled",
"password"
],
"properties": {
"id": {
"type": "string",
"example": "username",
"description": "User identifier"
},
"password": {
"type": "string",
"example": "password",
"description": "User's password. Please note that some services may return a distorted password (always 'XXXXX'). See the documentation of individual services to find out whether the password is returned as plain text or as 'XXXXX'."
},
"email": {
"type": "string",
"example": "[email protected]",
"description": "User's email address"
},
"phone": {
"type": "string",
"example": "+49 99 999999-999",
"description": "User's phone number"
},
"isAutoUpdateEnabled": {
"description": "Whether the user's bank connections will get updated in the course of finAPI's automatic batch update. Note that the automatic batch update will only update bank connections where all of the following applies:
- the PIN is stored in finAPI for the bank connection, and the related bank does not have volatile PINs (see the ‘pinsAreVolatile’ flag of the Bank Resource)
- the user has accepted the latest Terms and Conditions (this only applies to users whose mandator has PISP license or doesn't have a license at all)
- the user has allowed finAPI to use his old stored credentials (this only applies to users which had stored credentials before introducing a web form feature and whose mandator has PISP license or doesn't have a license at all)
- the previous update using the stored credentials did not fail due to the credentials being incorrect (or there was no previous update with the stored credentials)
- the bank that the bank connection relates to is included in the automatic batch update (please contact your Sys-Admin for details about the batch update configuration)
- at least one of the bank's supported data sources can be used by finAPI for your client (i.e.: if a bank supports only web scraping, but web scraping is disabled for your client, then bank connections of that bank will not get updated by the automatic batch update)
Also note that the automatic batch update must generally be enabled for your client in order for this field to have any effect.
WARNING: The automatic update will always download transactions and security positions for any account that it updates! This means that the user will no longer be able to download just the balances for his accounts once the automatic update has run (The 'skipPositionsDownload' flag in the bankConnections/update service can no longer be set to true).",
"example": true,
"type": "boolean"
}
},
"description": "Container for a user's data"
},
"UserCreateParams": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "username",
"description": "User's identifier. Max length is 36 symbols. Only the following symbols are allowed: 0-9, A-Z, a-z, -, _, ., +, @. If not specified, then a unique random value will be generated.",
"pattern": "[a-zA-Z0-9\\-_\\.\\+@]*"
},
"password": {
"type": "string",
"example": "password",
"description": "User's password. Minimum length is 6, and maximum length is 36. If not specified, then a unique random value will be generated.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"email": {
"type": "string",
"example": "[email protected]",
"description": "User's email address. Maximum length is 320.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"phone": {
"type": "string",
"example": "+49 99 999999-999",
"description": "User's phone number. Maximum length is 50.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"isAutoUpdateEnabled": {
"default": false,
"description": "Whether the user's bank connections will get updated in the course of finAPI's automatic batch update. Note that the automatic batch update will only update bank connections where all of the following applies:
- the PIN is stored in finAPI for the bank connection
- the user has accepted the latest Terms and Conditions (this only applies to users whose mandator has PISP license or doesn't have a license at all)
- the user has allowed finAPI to use his old stored credentials (this only applies to users which had stored credentials before introducing a web form feature and whose mandator has PISP license or doesn't have a license at all)
- the previous update using the stored credentials did not fail due to the credentials being incorrect (or there was no previous update with the stored credentials)
- the bank that the bank connection relates to is included in the automatic batch update (please contact your Sys-Admin for details about the batch update configuration)
Also note that the automatic batch update must generally be enabled for your client in order for this field to have any effect.
WARNING: The automatic update will always download transactions and security positions for any account that it updates! This means that the user will no longer be able to download just the balances for his accounts once the automatic update has run (The 'skipPositionsDownload' flag in the bankConnections/update service can no longer be set to true).
If not specified, then the automatic update will be disabled by default (false).",
"example": true,
"type": "boolean"
}
},
"description": "User details"
},
"UserIdentifiersList": {
"type": "object",
"required": [
"deletedUsers",
"nonDeletedUsers"
],
"properties": {
"deletedUsers": {
"type": "array",
"example": [
"first_user",
"second_user"
],
"description": "List of identifiers of deleted users (in ascending order)",
"uniqueItems": true,
"items": {
"type": "string"
}
},
"nonDeletedUsers": {
"type": "array",
"example": [
"third_user",
"fourth_user"
],
"description": "List of identifiers of not deleted users (in ascending order)",
"uniqueItems": true,
"items": {
"type": "string"
}
}
},
"description": "Container for list of identifiers of deleted users, and not deleted users (in ascending order)"
},
"UserIdentifiersParams": {
"type": "object",
"required": [
"userIds"
],
"properties": {
"userIds": {
"type": "array",
"example": [
"first_user",
"second_user",
"third_user",
"fourth_user"
],
"description": "List of user identifiers",
"items": {
"type": "string"
}
}
},
"description": "User identifiers params"
},
"UserInfo": {
"type": "object",
"required": [
"bankConnectionCount",
"registrationDate",
"userId"
],
"properties": {
"userId": {
"type": "string",
"example": 1,
"description": "User's identifier"
},
"registrationDate": {
"type": "string",
"example": "2018-01-01",
"description": "User's registration date, in the format 'YYYY-MM-DD'"
},
"deletionDate": {
"type": "string",
"example": "2018-01-31",
"description": "User's deletion date, in the format 'YYYY-MM-DD'. May be null if the user has not been deleted."
},
"lastActiveDate": {
"type": "string",
"example": "2018-01-31",
"description": "User's last active date, in the format 'YYYY-MM-DD'. May be null if the user has not yet logged in."
},
"bankConnectionCount": {
"type": "integer",
"format": "int32",
"example": 5,
"description": "Number of bank connections that currently exist for this user."
},
"latestBankConnectionImportDate": {
"type": "string",
"example": "2018-01-01",
"description": "Latest date of when a bank connection was imported for this user, in the format 'YYYY-MM-DD'. This field is null when there has never been a bank connection import."
},
"latestBankConnectionDeletionDate": {
"type": "string",
"example": "2018-01-31",
"description": "Latest date of when a bank connection was deleted for this user, in the format 'YYYY-MM-DD'. This field is null when there has never been a bank connection deletion."
},
"monthlyStats": {
"type": "array",
"description": "Additional information about the user's data or activities, broken down in months. The list will by default contain an entry for each month starting with the month of when the user was registered, up to the current month. The date range may vary when you have limited it in the request.
Please note:
• this field is only set when 'includeMonthlyStats' = true, otherwise it will be null.
• the list is always ordered from the latest month first, to the oldest month last.
• the list will never contain an entry for a month that was prior to the month of when the user was registered, or after the month of when the user was deleted, even when you have explicitly set a respective date range. This means that the list may be empty if you are requesting a date range where the user didn't exist yet, or didn't exist any longer.",
"items": {
"$ref": "#/definitions/MonthlyUserStats"
}
},
"isLocked": {
"description": "Whether the user is currently locked (for further information, see the 'maxUserLoginAttempts' setting in your client's configuration). Note that deleted users will always have this field set to 'false'.",
"example": false,
"type": "boolean"
}
},
"description": "Container for user information"
},
"UserUpdateParams": {
"type": "object",
"properties": {
"email": {
"type": "string",
"example": "[email protected]",
"description": "User's new email address. Maximum length is 320. Pass an empty string (\"\") if you want to clear the current email address.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"phone": {
"type": "string",
"example": "+49 99 999999-999",
"description": "User's new phone number. Maximum length is 50. Pass an empty string (\"\") if you want to clear the current phone number.",
"pattern": "[A-Za-z0-9¡-ʯ &\\(\\)\\{\\}\\[\\]\\.:,;\\?!\\+\\-_\\$@#~`\\^€]*"
},
"isAutoUpdateEnabled": {
"description": "Whether the user's bank connections will get updated in the course of finAPI's automatic batch update. Note that the automatic batch update will only update bank connections where all of the following applies:
- the PIN is stored in finAPI for the bank connection
- the user has accepted the latest Terms and Conditions (this only applies to users whose mandator has PISP license or doesn't have a license at all)
- the user has allowed finAPI to use his old stored credentials (this only applies to users which had stored credentials before introducing a web form feature and whose mandator has PISP license or doesn't have a license at all)
- the previous update using the stored credentials did not fail due to the credentials being incorrect (or there was no previous update with the stored credentials)
- the bank that the bank connection relates to is included in the automatic batch update (please contact your Sys-Admin for details about the batch update configuration)
Also note that the automatic batch update must generally be enabled for your client in order for this field to have any effect.
WARNING: The automatic update will always download transactions and security positions for any account that it updates! This means that the user will no longer be able to download just the balances for his accounts once the automatic update has run (The 'skipPositionsDownload' flag in the bankConnections/update service can no longer be set to true).",
"example": true,
"type": "boolean"
}
},
"description": "User details"
},
"VerificationStatusResource": {
"type": "object",
"required": [
"isUserVerified",
"userId"
],
"properties": {
"userId": {
"type": "string",
"example": "username",
"description": "User's identifier"
},
"isUserVerified": {
"description": "User's verification status",
"example": true,
"type": "boolean"
}
},
"description": "User's verification status"
},
"WebForm": {
"type": "object",
"required": [
"id",
"status",
"token"
],
"properties": {
"id": {
"type": "integer",
"format": "int64",
"example": 1,
"description": "Web form identifier, as returned in the 451 response of the REST service call that initiated the web form flow."
},
"token": {
"type": "string",
"example": "03FhQiom8CJUL7rkRgBMCOF9KXlGL9p7kPpW4puMKDD5QbeRm9E9Vzr1xBcokaxZt5PGRscn8HI8xuL8voLkirocxgFIF7wU8B240R5ccSjfPru9vXTBHBEycmBs8Rk2",
"description": "Token for the finAPI web form page, as contained in the 451 response of the REST service call that initiated the web form flow (in the 'Location' header)."
},
"status": {
"type": "string",
"example": "COMPLETED",
"description": "Status of a web form. Possible values are:
• NOT_YET_OPENED - the web form URL was not yet called;
• IN_PROGRESS - the web form has been opened but not yet submitted by the user;
• COMPLETED - the user has opened and submitted the web form;
• ABORTED - the user has opened but then aborted the web form, or the web form was aborted by the finAPI system because it has expired (this is the case when a web form is opened and then not submitted within 20 minutes)",
"enum": [
"NOT_YET_OPENED",
"IN_PROGRESS",
"COMPLETED",
"ABORTED"
]
},
"serviceResponseCode": {
"type": "integer",
"format": "int32",
"example": 201,
"description": "HTTP response code of the REST service call that initiated the web form flow. This field can be queried as soon as the status becomes COMPLETED or ABORTED. Note that it is still not guaranteed in this case that the field has a value, i.e. it might be null."
},
"serviceResponseBody": {
"type": "string",
"example": "{\n \"id\": 1,\n \"bankId\": 277672,\n \"bank\": {\n \"id\": 277672,\n \"name\": \"FinAPI Test Bank\",\n \"loginHint\": null,\n \"bic\": null,\n \"blz\": \"00000000\",\n \"blzs\": [\n \"00000000\"\n ],\n \"loginFieldUserId\": \"Onlinebanking-ID\",\n \"loginFieldCustomerId\": null,\n \"loginFieldPin\": \"PIN\",\n \"isSupported\": true,\n \"supportedDataSources\": [\n \"FINTS_SERVER\"\n ],\n \"pinsAreVolatile\": false,\n \"location\": null,\n \"city\": null,\n \"isTestBank\": true,\n \"popularity\": 7,\n \"health\": 100,\n \"lastCommunicationAttempt\": \"2018-01-01 00:00:00.000\",\n \"lastSuccessfulCommunication\": \"2018-01-00 00:00:00.000\"\n },\n \"name\": null,\n \"bankingUserId\": \"XXXXX\",\n \"bankingCustomerId\": null,\n \"bankingPin\": null,\n \"type\": \"DEMO\",\n \"updateStatus\": \"READY\",\n \"categorizationStatus\": \"READY\",\n \"lastManualUpdate\": null,\n \"lastAutoUpdate\": null,\n \"twoStepProcedures\": [],\n \"ibanOnlyMoneyTransferSupported\": false,\n \"ibanOnlyDirectDebitSupported\": false,\n \"collectiveMoneyTransferSupported\": false,\n \"defaultTwoStepProcedureId\": null,\n \"accountIds\": [\n 1\n ],\n \"owners\": null\n}",
"description": "HTTP response body of the REST service call that initiated the web form flow. This field can be queried as soon as the status becomes COMPLETED or ABORTED. Note that it is still not guaranteed in this case that the field has a value, i.e. it might be null."
}
},
"description": "Container for a web form's data"
}
}
}