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
- 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 right to specific organizations. A user have access to multiple organization and an orgainzation can have multiple users.

Postman Collection
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 bepassword
.client_id
: Yourclient_id
part of your API credentials.client_secret
: Yourclient_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 futher API calls, by supplying it in 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 the 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 to obtain the scanned data.
To get 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
.
successful
, the data is ready, and is returned through the above endpoints.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.
- FTP: You can set up an organization to have all finished data delivered on a FTP, which we provide.
- ERP-integration: By setting up an integration to a supported ERP-system, Paperflow will deliver the finished voucher with data to the ERP-system.
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.