FinAPI

FinAPI aims to provide a simple-to-use and easy-to-implement API for managing financial and insurance-related data.

FinAPI defines:

WHAT: The format and content of the data
HOW: The methods for delivery, transfer, and authentication
ONBOARDING: The process for becoming a user of FinAPI

This is achieved through three prime directives:

Simple to use: accessible via a REST API with private/public key authentication
Easy to implement: thanks to a flat data structure and no pagination
Easy to onboard: involves filling out a single form and awaiting approval

1. Test it

Discover how our API works by testing it directly on this page.
Options include:

using the (prefilled) demo account
or, if you have an existing account, using your own JWT Payload and Private Key

To obtain your own JWT Payload and Private Key, please complete the Onboarding Form.

1a. Generate a Json Web Token (JWT)

Enter your JWT Payload and Private Key to generate a JWT or use the prefilled demo auth and private key.

A JWT is needed to make an authenticated API call.

Resulting JWT

1b. Make API calls using the OpenAPI Docs

Copy the JWT
Open https://finapi.finum.at/v1/docs/
Click on "Authorize" (right top)
Paste the JWT into the bearerAuth input field and hit the "Authorize" Button
Then you can click on any endpoint like "auth-status"
By clicking the button "Try it out" and then the button "Execute" you can test the API

2. I am a consumer and I want to use it

Once you have a good understanding of how auth works and what each endpoint offers, you can start using it. For testing purposes, you can use the demo account. For production, you will need to complete the Onboarding Form.

Quick Tip: Be sure to check out the Schemas in the OpenAPI docs to see which info you can get.

Typically, there are four use cases:

2a. Use case: Get the latest data for a specific contract

Useful if you are currently reviewing a contract and want to ensure it's up to date

Use the contract-list/?id-list=123,43948,123 endpoint

2b. Use case: Get an overview of all the contracts for a given client

Useful if you want to give the user an overview of all his contracts

Use the contract-list/?holder-id=123 endpoint

2c. Use case: Sync all contracts that have changed in the last 7 days

Useful if you want to keep your local data up to date periodically

This requires two API calls:

First get a list of all contracts that got updated via `contract-id-list-updated`
Then get the details of all these contracts `contract-list/?id-list=123,43948,123`

3. Implement your own

If you are a provider and want to implement your own FinAPI, you can use the OpenAPI docs to see what endpoints are available.

Going Live:

We recommend to publish it at https://finapi.your-company.com
Onboarding should accordingly be at https://finapi.your-company.com/onboarding/

Validation:

Ensure you follow the OpenAPI docs exactly as written. If you have any questions, feel free to ask.
You can validate your own API at any time. We're ready when every endpoint is green 😊

FAQ

Yes, providers can add any property they want as long as they are prefixed with an _. For example, if a provider wants its FinAPI users to know if a client has ever been in debt, they could add a property like _hasEverBeenInDebt to the client endpoint.

Important: Nested Object properties prefixed with an _ are possible but discouraged.

Yes, if a contract gets terminated, it should still be transferred with the appropriate status.

In Short: Pagination adds complexity for both the consumer and provider sides, which contradicts two of our prime directives: "Easy to implement" and "Simple to use." Moreover, our updated endpoints can handle over 50,000 entries in a single call, making pagination unnecessary.

Longer Explanation: Assuming a cautious 5MB limit to facilitate seamless serverless function usage, about 1.2 million characters are available under UTF-8 encoding. By only transferring IDs (averaging about 20 characters each) of, for example, contracts that have changed, we can safely transfer more than 50,000 IDs in one go. Therefore, no pagination is needed for the updated endpoints in 99.9% of the cases.
If a single consumer has significantly more than 50,000 updated contracts, they can either make multiple requests using different time frames or use a server with a higher response limit than typical serverless functions. Both options are simpler than implementing pagination.

We recommend storing foreign IDs, such as the contract ID from a foreign system, in your local contract data (for example, as `foreignId`) to help keep your local data synchronized with the foreign system.