Getting Started – Boyum Help Center

You have just received API credentials for the Paperflow API, and are wondering where to start. This document will guide you through the steps needed, and some of the different options for integration.

Paperflow API is a REST-based API, and we assume you are familiar with performing HTTP calls.

Core concepts

The first thing you need to understand about the Paperflow API is our 3 core concepts.

Voucher - a voucher represents an invoice. When an invoice file is uploaded to Paperflow a voucher object is automatically created containing the original file and the data that we extract from said file.
Organization - an organization represents your clients. For each client with a unique vat reg, no you will have to create a corresponding organization in Paperflow. An organization can then have many vouchers to it, and a voucher will always belong to one single organization
User - a user handles access rights to specific organizations. A user has access to multiple organizations and an organization can have multiple users.

Authorization

First, you need to authorize. Paperflow API uses a simplified version of OAUTH2.0. To use any endpoint, you first need to obtain an “authorization token”, that you then supply in each call to the API. You use your API credentials to obtain this token, by calling the endpoint /oauth2/token, with the following fields in the body:

grant_type: Must be password.
client_id: Your client_id part of your API credentials.
client_secret: Your client_secret part of your API credentials.
email: Your primary API user - given as part of your API credentials.
password: The password for your primary API user - initially given as part of your API credentials, but can be changed by you.

The obtained token can now be used in all further API calls, by supplying it in the headers with: Authorization: Bearer yourtokengoeshere.

Create an organization

In order to upload a voucher to be scanned, you first need to create an organization. A voucher belongs to a specific organization, and the organization should be either the recipient or the sender of the voucher. Paperflow uses information from the organization, such as address and VAT number to aid in the scanning.

To create an organization, you use the endpoint Create Organization POST /v1/user/organizations. See the documentation for details.

Upload a voucher

When you want to upload a voucher, you need the ID of the organization you want to upload the voucher for. This is returned from the Create Organization endpoint or can be obtained by listing your organizations.

Once you have the ID for the organization, you can upload a voucher by calling POST /v1/organizations/{id}/vouchers. In the response returned, you can see the ID for the voucher. Since the scanning is performed in the background, it might take some time for the data to be ready. You can use the ID of the voucher to query the status and obtain the scanned data.

To get the status on a single voucher, you use the endpoint GET /v1/vouchers/{id}, or you can list all vouchers for an organization with the endpoint GET /v1/organizations/{id}/vouchers.

As soon as the status of the voucher is successful, the data is ready and is returned through the above endpoints.

If you want to keep track of which vouchers you have already processed on your end, when listing all vouchers, Paperflow has the option for you to mark individual vouchers as seen by you. Use the endpoint MarkVoucherAsSeen, which also has a detailed description of this feature.

To avoid polling the API for the finished voucher data, we recommend you use one of the other methods:

Callback URL: By setting a callback URL for the voucher when it is being uploaded, we will call the URL once the voucher is done, and supply the ID of the voucher. You can then obtain the data from the API as needed.
Websocket: You can subscribe to our WebSocket, and we will push status changes for vouchers over this channel.
SFTP: You can set up an organization to have all finished data delivered on an SFTP, which we provide.

Activating Validated Scan

Validated Scan is an add-on product that can be added to an organization. Internally, this is a product called HDR (Human Data review) and is referred to as such.

In order to activate this product, you need the endpoints listed under products in the API documentation. First, you list the available products to obtain the ID of the HDR product, and then you add this to your organization.

After adding the product to the organization, you will need to toggle validation on the specific fields for the organization. The endpoint is listed under fields in the API documentation. In this endpoint, you will need to add the following code to the body along with the field ID: "validation": true

Rate limiting

In order to control the incoming traffic Paperflow utilizes rate limiting for each client. Paperflow uses the leaky bucket algorithm to control this. Each client starts with a maximum request pool of 50 and gets 2 extra requests each second. If the client exceeds this limit the API will respond with an HTTP code 429.

Note: this does not apply to uploading invoices.

The rate limiting is in place to protect our systems against abuse, and normal use should never hit our limits. In case you hit the limit, please check our API documentation for an endpoint that might suit you better.