API Documentatie
Introduction
This documentation describes the functionality of the FinBuddy API and webhook. It includes details about authentication, available endpoints, request and response formats, and error handling.
If you have any questions or feedback after reading this documentation, feel free to contact us at support@finbuddy.nl.
Connecting to the FinBuddy API
You can access the FinBuddy API via https://api.finbuddy.nl/webapi/
Authentication
The FinBuddy platform and API can be accessed with an API key. The API keys are managed by FinBuddy. You can request an API key via support@finbuddy.nl.
Each customer has a unique API key. If you expect to integrate more than one client, you will need to build the integration in a way that you can support multiple API keys.
Authentication is done by placing the API key as a header of the request with the name ‘ApiKey’.
Customers
FinBuddy allows you to retrieve all the requests from customers who would like to change their payment date. These customers have gone through the FinBuddy flow and are awaiting approval/rejection or have already been processed by the vendor.
There are several actions you can execute:
- Retrieve a list of all requests
This can be achieved by performing a get call to https://api.finbuddy.nl/webapi/customers This will return the following:
{ “items”: [ { “id”: “3e903b6a-e2ae-4376-1eda-08dd50e7a43b”, “initials”: “F.B.”, “lastName”: “van de Test”, “emailAddress”: “customer@customer.nl”, “iban”: “NL50INGB0328578754”, “newDebtCollectionDay”: 23, “address”: { “street”: “Parallelweg”, “houseNumber”: “27”, “postalCode”: “5223AL”, “city”: “’s-Hertogenbosch”, “country”: “NL” }, “dateOfBirth”: “1986-08-02”, “phoneNumber”: “+31612345678” } ], “currentPage”: 1, “pageSize”: 1 } |
- Retrieve a filtered list of requestsThere are a few filters you can apply:
- The FinBuddy API supports pagination through the following parameters:
- currentPage=x
- pageSize=x
- The FinBuddy API supports pagination through the following parameters:
This translates to a GET request in a format such as this one:
| https://api.finbuddy.nl/webapi/customers?currentPage=1&pageSize=50 |
- Status
The ‘isConfirmed’ filter can be used to filter between either processed or unprocessed requests. The value ‘false’ gives a result of all the requests that are currently ‘open’ and ready for approval or rejection. The value ‘true’ gives all the requests that have already been processed in the past. The GET call is as follows:
- Status
| https://api.finbuddy.nl/webapi/customers?isConfirmed=false |
- DateThe ‘completedAtFrom’ parameter is used to filter requests from a certain date and/or time
| https://api.finbuddy.nl/webapi/customers?completedAtFrom=2025-04-8T11:30:00 |
Individual customer
You can use the “id” of a customer to perform a GET call for a specific customer. The request (for example) is as follows:
| https://api.finbuddy.nl/webapi/customers/c42c4ee4-3aa6-4eaa-435e-08dd6d38822c |
This returns the following:
{ “id”: “3e903b6a-e2ae-4376-1eda-08dd50e7a43b”, “initials”: “F.B.”, “lastName”: “van de Test”, “emailAddress”: “customer@customer.nl”, “iban”: “NL50INGB0328578754”, “newDebtCollectionDay”: 23, “address”: { “street”: “Parallelweg”, “houseNumber”: “27”, “postalCode”: “5223AL”, “city”: “’s-Hertogenbosch”, “country”: “NL” }, “dateOfBirth”: “1986-08-02”, “phoneNumber”: “+31612345678” } |
Process a request
A request can either be approved or rejected.
Approval
To approve a request, you can perform the following POST
URL: https://api.finbuddy.nl/webapi/customers/acknowledge Body: { “id”: “3e903b6a-e2ae-4376-1eda-08dd50e7a43b”, “startDebtCollectionDate”: “2025-06-05T07:31:08.741Z” } |
The startDebtCollectionDate should contain the date on which the new direct debit date will come into effect. The FinBuddy user receives an automatic confirmation e-mail as a result of this request.
Rejection
There are several reasons as to why a request can be rejected. Each reason triggers a specific e-mail to the FinBuddy user informing them why their request has been rejected. The reason can be specified via the API with a code. The following reasons can be used:
| Reason | Code |
| Unknown customer | 1 |
| Newly requested date is already the current payment date, so no change needs to be made | 2 |
| The customer does not pay with direct debit | 3 |
| Incorrect bank account | 4 |
| No authorization (contract not in the name of the person requesting the change) | 5 |
| No permission, for instance because the user is customer is under guardianship and is not allowed to make changes | 6 |
| Other | 7 |
This results in the following call:
URL: https://api.finbuddy.nl/webapi/customers/decline Body: { “id”: “3e903b6a-e2ae-4376-1eda-08dd50e7a43b”, “reason”: 1, “message”: “string” } |
The “id” refers to the FinBuddy identifier of the customer. The identifier is included in the GET call under the customers section of this manual.
Webhook
You can use a webhook to receive a notification on the event that a new request is ready for processing. To set it up, send an e-mail to support@finbuddy.nl with the URL for the webhook. You will receive a confirmation when the webhook is activated.
The webhook will send the following message:
{ “id”: “3e903b6a-e2ae-4376-1eda-08dd50e7a43b” } |
The “id” provided is the identifier of the customer. This identifier can be used to perform a ‘customers get call’ as described in the chapter ‘Customer’.
Questions and support
Feel free to contact is if you need any help or assistance. We are more than happy to help out. Any feedback to make this manual or our API better is also very welcome. You can contact us via support@finbuddy.nl.