This is the currently supported stable version of the Silverfin API - version 4.

If you need information about migrating from the deprecated version 3 to version 4, please read: https://engineering.silverfin.com/silverfin-api-v4.

Authorization flow implements OAuth2 so you need a client_id and client_secret to connect. This can be requested by a mail to api@getsilverfin.com

API Mailing list

You can subscribe to our mailing list if you want to be kept up-to-date regarding any change we push on our API.

API changes

Non-breaking changes, such as adding data to a payload or implementing a new endpoint, can happen at any time without any advance warning.
Breaking changes, such as removal of data from a payload or removal of an endpoint, will be communicated in advance, with the length of deprecation notice proportional to scope & impact of the change.

OAuth endpoints

Authorization

When you redirect to the authorize url, you can pass the requested scopes in the url with the scope parameter. The scopes should be separated with spaces.

You have two options when requesting authorization:

url without firm_id: /oauth/authorize
url with firm_id: /f/:firm_id/oauth/authorize

Note that in either case the user will have the option to authorize access to any of the firms they belong to. If /f/:firm_id is included in the URL, the selector presented to the user will pre-select this firm, but you should not assume that access will be granted to the firm you requested.

In addition to the authorization code, the response will contain an additional url parameter authorized_firm_id, denoting the firm to which your application has been granted access. Please be sure to make note of it as you will need it for all subsequent requests.

Access token request

url must include firm_id: /f/:firm_id/oauth/token

OAuth flow

We use standard OAuth. The typical flow goes like this:

Perform a GET request to /oauth/authorize with url parameters client_id, redirect_uri, scope (a space separated list of requested scopes) and response_type=code
Once the user grants your app permission to access their data, the browser will redirect to redirect_uri with a url parameter code
With this code, your application will have 10 minutes to perform a POST request to /oauth/token with parameters client_id, client_secret, code, redirect_uri and grant_type=authorization_code

After following these steps, you will have an access token and a refresh token. The access token is valid for 2 hours, while the refresh token currently does not expire.

NOTICE: As of August 9, 2022, refresh tokens will remain valid for 60 days. Please read our announcement for more details.

With the refresh token, you can request a new access token / refresh token pair:

Perform a POST request to /oauth/token with parameters: client_id, client_secret, refresh_token, redirect_uri and grant_type=refresh_token.

Each refresh token can be used only once. As soon as the new access token is used to access the API for the first time, the previous refresh token will be revoked.

Scopes

We currently support the following scopes: administration:read, administration:write, communication:read, communication:write, financials:read, financials:write, financials:transactions:read, financials:transactions:write, links, permanent_documents:read, permanent_documents:write, user:email, user:firm, user:profile, webhooks, workflows:read, workflows:write

The scopes are also coupled to the application and added to the application based on your needs.

Error codes

When an error occurs, we return a response with a specific status code and a JSON payload with the following format:

{
  error: "A message describing the issue."
}

Please referer to the following table when you receive such an error:

Code	Description	How to handle
400	Bad Request. We will not process the request due to an apparent error.	See error for details. Then re-submit the request with your input fixed.
401	Unauthorized. The Auth token is not valid.	Check that the Authorization header is properly set and still valid.
403	Forbidden. The user does not have the necessary permissions for the resource, or is attempting a prohibited action.	See error for details. Request another Auth token with proper scopes to perform this action, or re-submit the request with your input fixed.
404	Not Found. The requested resource could not be found.	-
409	Conflict. The request could not be processed because of conflict in the current state of the resource.	See error for details. Then re-submit the request with your input fixed.
422	Unprocessable Entity. The request was well-formed but was unable to be followed due to semantic errors.	See error for details. Then re-submit the request with your input fixed.

API formats

The Silverfin API supports application/pdf, application/json and application/vnd.openxmlformats-officedocument.spreadsheetml.sheet media types as Content-Type values.

If the body is present in a request, with a Content-Type header value that is of an unsupported type a "415 Unsupported Media Type" error code will be returned by the Silverfin API.

In case the Content-Type header is missing or malformed the API will return a 403 Forbidden response.

Internationalization

Endpoint outputs and generated documents can be translated by passing the Accept-Language header, such as:

curl -X GET --header 'Accept: application/json' --header 'Accept-Language: nl' --header 'Authorization: ...' 'http://localhost:3000/api/v4/f/...'

API Key	Label	Last Used