Data export

Scenario outline

Data can be exported from the Skovik UI and via the API. The same data formats are available in both interfaces.

The most common export formats are for integration with bookkeeping or payroll software, but there are other formats too.

If you want to use our API for data export, we recommend the following approach.

Decide on an export format

Start with finding an export format that fits your needs. The easiest way to explore the available export formats is to use our desktop UI where it is also possible to download example files.

There is also an endpoint listing available formats and their options. Those options are passed under the options key, nested under attributes in the POST request.

Select a branch

Larger organisations with multiple branches will make one export per branch. If your company doesn't have multiple branches, disregard this section.

Note that export formats can vary depending on the country your branch is in. For example, a Canadian branch will not have access to some Finland-specific export formats.

Branches are identified by an ID. This ID can be accessed using the branches endpoint. You may either hard-code this branch ID in the export script, or look it up at the start of the script using the external_identifier.

Write the code

For exports we recommend a scheduled-based integration. If you have multiple branches, the steps below will be performed once per branch.

Make a POST request to the Create export order endpoint.
Parse the response you get back. It will contain the ID of the newly created export order.
The export order is queued and processed asynchronously in our system. It will take a few moments for it to complete.

Most exports complete within 5-30 seconds, but large exports (a long time span or a lot of data) may take much longer to complete.
Poll the Read export order endpoint with the ID of the newly created export order.

A reasonable polling frequency is 10-60 seconds and your script would pause in between each poll. If the export order has the completed state, the response will contain an URL to the export file.

Make a GET request to the file URL to download the actual export file. Make sure this request will follow any HTTP redirects.

Things to keep in mind

📘
Export format versioning
While we try to avoid breaking changes in export formats, there will be changes from time to time.
The API versioning cover our API endpoints, but not the content of exported data. Instead, their versioning is handled via our »Calculation engine versioning«, which is accessed via our desktop UI.
When there are several export formats that contain the data you need, choose one that is based on JSON or XML, since it's easier to parse them defensively.
More specifically, look up values by key (not by the order in which they appear in the dictionary/hash).