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

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


Core concepts

The first thing you need to undertand about the Bilagscan API are our 3 core concepts. We have made a video tutorial explaining this in detail, please watch this first: Danish - English


  • Voucher - a voucher represents an invoice. When an invoice file is uploaded to Bilagscan 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 Bilagscan. 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

If you have received a postman collection from us in order to test our API, please read this article:

Authorization

First you need to authorize. Bilagscan 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 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. Bilagscan 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.


As soon as the status on 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, Bilagscan has the option for you to mark individual vouchers as seen by you. Use the endpoint MarkVoucherAsSeen, which also has 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.
  • 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, Bilagscan will deliver the finished voucher with data to the ERP-system.

Activating 100% correct data

100% scanning 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 description. First you list the available products to obtain the ID of the HDR product, and then you add this to your organization.


Rate limiting

Bilagscan's API is rate limited. If you perform too many requests within a short timespan, you will get an appropriate HTTP error of 429. In this case, you can wait a few seconds, and try again.
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.