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 [email protected]
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: https://live.getsilverfin.com/oauth/authorize
url with firm_id: https://live.getsilverfin.com/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: https://live.getsilverfin.com/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:
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: