FiNUM Sync API LogoFiNUM Sync API

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

FiNUM Sync API defines:

This is achieved through three prime directives:

  1. Simple to use: accessible via a REST API with private/public key authentication
  2. Easy to implement: thanks to a flat data structure and no pagination
  3. 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:
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.

1b. Make API calls using the OpenAPI Docs

  1. Copy the JWT
  2. Open https://syncapi.finum.at/v1/docs/
  3. Click on "Authorize" (right top)
  4. Paste the JWT into the bearerAuth input field and hit the "Authorize" Button
  5. Then you can click on any endpoint like "auth-status"
  6. 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:

  1. First get a list of all contracts that got updated via `contract-id-list-updated`
  2. 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 FiNUM Sync API, you can use the OpenAPI docs to see what endpoints are available.

Going Live:

Validation:

Connecting with us:

4. Common Flows

Most commonly you will want to use one of these flows:

Syncing data from provider to your database

Say you want to keep your database up to date with changes made by the provider. In most cases you will want to do this periodically, therefore you want to import all changes made to the providers database since your last sync.

1. find the ids of all changed contracts by calling /contract-id-list-updated?since={lastPullDate}.

2. to get the actual data, use the ids returned before to call /contract-list?id-list={ids recieved before}. This will return an array containing the data of all changed contracts.

3. the updated data can then be applied to your own database.

Repeat this process for all record types (contract, client, product, user, file). To completely synchronize the providers and your database.

Creating new contracts with a provider

The other big use case of FiNUM Sync API is to create new contracts with providers. To to this the following flow should be adhered to:

1. Get all the data you need from your customer, including their data as well as the contract data.

2 Check if the client already has an id in the providers database, by checking your external id field.

3. If they don't, call POST /client with the customer data in the request body. The provider will return the client after creation, i.e. with all necessary data like id added.

4. Create a contract with the data gathered from the customer by calling POST /contract with the request body containing the contract data and a status of 120 ("Create Proposal"). This tells the provider that we have given them all necessary data, and a proposal should be created. You may also add a callback, which the provider will call when the contract status is next changed. The provider will return the contract after creation. This will have all fields filled like they should be.

The data you provided might not be enough for a status of 120 ("Create Proposal"), you might be missing some option for example. The provider should then return a status of 110 ("Wait for client data") to reflect this fact.

5. After some time the provider will have created a proposal like we asked them to do. You will then get a callback as specified informing you that the contract status has changed. This callback includes the contract id. You will need to get the data by calling /contract-list?id-list={id recieved}. If the creation was successful this status should now be 130 ("Proposal available"). You can find the id of this proposal file in the contract data and may download it at the appropriate endpoint.

6. Now that you have the proposal you should ask your customer for permission to order the contract as offered.

Otherwise you can call PATCH /contract with the changed contract data and again a status of 120 ("Create Proposal") to make changes.

7. As soon as you and your customer are happy with the proposal you update the contract status by calling PATCH /contract with the providers contract id and the status field. In this case you want to change status to 230 ("Proposal sent") to tell the provider to start processing your order. You can also add a callback here.

8. After some time you get a callback from the provider inform you of another status update. This should hopefully be 320 ("active"). Now the contract should also contain some new documents corresponding to the active status. You may download them as before.

While the callback based flow is really useful for being very responsive, it is more complex to implement. If you are fine with updates only once a day for example you can periodically query the pending contracts to see the status changes

FAQ

Yes, providers can add any property they want as long as they are prefixed with an _. For example, if a provider wants its FiNUM Sync API 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.