Introduction

This document describes the public REST API of Zenvoices.

• OpenAPI specification: https://app.zenvoices.com/swagger/docs/public-v1
• Swagger UI (interactive documentation): https://app.zenvoices.com/swagger/
• The API base URL is https://app.zenvoices.com/public-api/v1/.
• Only application/json content is supported.

Refer to chapter Available APIs for an overview of supported featrues.

Getting started

Register for API access

If you don’t have access to a Zenvoices user/tenant yet, start your free trial here.

Grant API access to a user

The Zenvoices public API uses bearer tokens for authentication. A bearer token can be retrieved by passing user login credentials to POST /api/Account/Authenticate. API requests are executed with the permissions of the user used for authentication. Users don’t have API access by default, therefore we first need to grant API access to a user of your tenant.

Go to Manage / Organisation / Users in the Zenvoices portal. Create a new user which is only used for API access (recommended) or use an existing user. Edit the permissions of the user and grant the API permissions you’d like to use.

Note: users with only API access are not billed.

Get a bearer token

Call POST /api/Account/Authenticate with your user credentials to get a bearer token. Bearer tokens are valid for 2 hours and are used to authenticate API requests.

Example cURL command:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json'  -d '{ \ 
   "tenancyName": "your-tenant-name", \ 
   "usernameOrEmailAddress": "your-api-username", \ 
   "password": "your-password" \ 
 }' 'https://app.zenvoices.com/api/Account/Authenticate'

Example response:

{ "result": "xl18nS1QZuh05KFLqMsNisezQCVwnseT2Rj6U9spPFd2RPb_e-4FzVxoZ4-wst-ug5ji7ztvNBtw-wMhqQ71qEZeVqP7qoVlLI9z9EUMgGVrv56oZQS5jELRp1C20IIgnYJWCA30IE8L_45WzZohduV2MAwRerCOXuoCogFuIpw3xYk4wp4AQQ2N69tUUd8oIh6ehbFQqmJ3bkUKP36U8LJWUUXMikFLRIdyoBYpKEEapBrny1Ln25BEb7ibDtBKUjwAeeqV7ZuF6geGx0dEx1OHW_x1IPzPESDm-xxoq4DqYy3WdeWZEH2cxOkWwBUlBXLcenZQhis8Ht3I0vUfBotyPNZpirDqfXNAyDnnxTMONVUEHnmVhud6oWB79_1xTd5aa5ai1rTNpClV6Cz_abdYfcIgzho02RrD1moP72Nix6Cajgw2FjMXSdEOydNChnkgecbV4F3_w_2EuWHNEAwu8JpMFat_jZGWYsCCF04azZIyQrg3NjUANbhiSks4vJy628UP40GqFqxfKSViQaWeUdIRkqykEx1zCp7xPMmhDZuJtViw_yDslmrNjnlW", "targetUrl": null, "success": true, "error": null, "unAuthorizedRequest": false, "__abp": true }

In the response above the result property contains the bearer token. In subsequent requests you must include this bearer token in the Authorization header with value “Bearer <bearer-token>”

Make your first API call

For example call POST /public-api/v1/air/processDocument using the following cURL command:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer <your-bearer-token>' -d '{ \ 
   "url": "https://your-domain/document.pdf", \ 
   "fileName": "document.pdf", \ 
   "legislation": "nl",   \ 
 }' 'https://app.zenvoices.com/public-api/v1/air/processDocument'

Go to our Swagger UI to discover all available operations and parameters.

Authentication

API calls are authenticated by providing an Authorization header using the Bearer scheme. A bearer token can be retrieved by passing user login credentials to POST /api/Account/Authenticate. API requests are executed with the permissions of the user used for authentication. We recommend using a separate user for API access.

Example Authorization header:

Authorization: Bearer <your-bearer-token>

Example cURL request to retrieve a bearer token:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json'  -d '{ \ 
   "tenancyName": "your-tenant-name", \ 
   "usernameOrEmailAddress": "your-api-username", \ 
   "password": "your-password" \ 
 }' 'https://app.zenvoices.com/api/Account/Authenticate'

Example of an authenticated cURL request with a bearer token:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer <your-bearer-token>' -d '{ \ 
   "url": "https://your-domain/document.pdf", \ 
   "fileName": "document.pdf", \ 
   "legislation": "nl",   \ 
 }' 'https://app.zenvoices.com/public-api/v1/air/processDocument'

Paging and sorting data

List endpoints support paging and sorting data.

Use the maxResultCount and skipCount input parameters to receive data in pages. The maximum result count per page is 250.

Use the sorting input parameter to sort data. The value of this parameter must be in the format: “[fieldname] [asc/desc], [fieldname] [asc/desc], …”. Sorting on all response fields is supported. If no sorting parameter value is provided, results will be sorted on the primary key.

Error handling

Error kind	HTTP response code	Description
Invalid input	400	This error is returned when invalid input is provided. error.validationErrors of the response body contains a list of invalid fields with related errors.
Unauthorized	403	This error is returned when you’re not authorized to access the request resource.
Entity not found	404	This error is returned when a requested entity doesn’t exist.
Too many requests	429	This error is returned when the rate limit of an endpoint is reached.
General error	500	This error is returned when an error occured during request processing. Refer to error.message in the response body for details about the error.

Limits and quotas

Max. requests per second per endpoint*	10
Max. items per page	250

* HTTP response code 429 is returned when the request limit is reached.

Data privacy and security

• Zenvoices is governed by strict standards regarding the privacy and protection of customer data. We take strong measures to protect your data from unauthorized persons or improper access.
• Zenvoices is ISO 27001:2017 and 9001:2015 certified and uses ISO 27001 certified infrastructure for hosting and data storage.
• More information about data privacy can be found in our privacy statement and data processing agreement.
• More information about security can be found here.

Client libraries

Currently no pre-built client libraries are available, but you can easily create your own client by leveraging our OpenAPI 2.0 specification, which is available on https://app.zenvoices.com/swagger/index.html?urls.primaryName=Zenvoices%20public%20API%20v1. For example, you can use Swagger Codegen to generate client libraries for languages such as C#, Java, PHP, Python, Perl, etc.

Swagger UI

Swagger UI is available on https://app.zenvoices.com/swagger/.

If you’re logged in to the Zenvoices portal (https://app.zenvoices.com), try out requests are authenticated as the user you’re currently logged in as.

If you’d like to authenticate try out requests as another user, login as this user in the Zenvoices portal or ensure you’re logged out in the Zenvoices portal (!) and enter a bearer token in the Swagger UI header’s api_key field. Note the latter only works when you’re not already logged in to the Zenvoices portal.

Available APIs

Accounting systems

This API allows you to list available accounting system connectors.

Administrations

This API is used to list administrations (companies) and get administration details. Only administrations that are granted for the authenticated user are accessible.

Automatic invoice recognition (AIR)

This API allows the use of Zenvoices automatic invoice recognition (AIR) machine learning technology to extract key-value pairs from invoice and receipt documents. It outputs structured data with details of the extracted values. You can train your own machine learning models to improve accuracy by providing feedback on recognition results.

Supported fields

Field name	Data type	Extracts single or multiple values?	Has confidence?	Supports training?	Description
InvoiceNumber	String	Single	Yes	Yes	Invoice number.
InvoiceDate	Date	Single	Yes	Yes	Date the invoice was issued.
DueDate	Date	Single	Yes	Yes	Date invoice payment is due.
Currency	String	Single	Yes	Yes	ISO 4217 currency code.
TotalAmountInclTax	Number	Single	Yes	Yes	Total amount including VAT (TotalAmountExclTax + sum of tax line amounts)
TotalAmountExclTax	Number	Single	Yes	Yes	Total amount excluding VAT
TaxLine	String	Multiple	False	Yes	Tax amount, tax rate and base amount separated by a semicolon (;). Up to three tax line fields can be extracted. Only tax lines with rates of the given legislation are extracted.
InvoiceCocNumber	String	Single	No	No	Chamber of commerce number.
InvoiceCustomerIdentifier	String	Single	No	No	Customer identifier.
AccountEmail	String	Single	No	No	E-mail address.
InvoiceIBAN	String	Single	No	No	IBAN (bank account number).
AccountPostalCode	String	Multiple	No	No	Postal code.
InvoiceVatNumber	String	Single	No	No	VAT number.
YourReference	String	Multiple	No	No	Reference numbers of purchase orders, receipts, etc.
StructuredPaymentReference	String	Single	No	No	Structured payment reference. Supported formats: ISO 11649 Creditor Reference, Belgian OGM (gestructureerde medeling).
TaxReverseChargedKeyword	Boolean	Single	No	No	Bool indicating if tax is reverse charged.
InvoiceKeyword	Boolean	Single	No	No	Bool indicating if the document is an invoice. If false, the document is a receipt.
CreditKeyword	Boolean	Single	No	No	Bool indicating if the document is a credit note. If True and extracted amounts are positive, you should change their sign to make them negative.

Excluding values from extraction

Using the “excludedValues” parameter of POST /public-api/v1/air/processDocument you can specify which field values should be excluded from extraction. For instance, if you’d like to extract data from purchase invoices you can exclude known customer account identifiers (such as VAT number and IBAN) to allow AIR to extract supplier account identifiers.

Custom models

Overview

You can train custom machine learning models to improve recognition accuracy. Custom models can be created using the endpoint POST /public-api/v1/air/model/createOrUpdate.

In the request body of the POST /public-api/v1/air/processDocument endpoint you can specify which model must be used for recognition using the modelId parameter. Our AI engine combines our pretrained models with your custom model to ensure optimal recognition accuracy on all features, even if the training data amount is small.

With the endpoint POST /public-api/v1/air/validateOperationResult you can provide feedback on process document operation results. This feedback is used to generate training data for your model.

After validating operation results, use the endpoint POST /public-api/v1/air/model/train to train your model.

Providing feedback

By providing feedback on process document operation results you can improve recognition accuracy and increase confidence values.

Use the POST /public-api/v1/air/validateOperationResult endpoint to provide feedback on a operation. You can only provide feedback on operations that used a custom model.

Example request body:

{
  "operationId": "37bc8616-ce2f-40e6-ad72-896dcfa7787e",
  "correctValues": [
    {
      "fieldName": "InvoiceNumber",
      "correctValue": "20150122"
    },
   {
      "fieldName": "InvoiceDate",
      "correctValue": "2019-01-02T00:00:00.0000000"
    },
   {
      "fieldName": "TotalAmountInclTax",
      "correctValue": "121.00"
    },
   {
      "fieldName": "TotalAmountExclTax",
      "correctValue": "100"
    },
   {
      "fieldName": "TaxLine1",
      "correctValue": "21.00;0.21;100.00"
    },
  ]
}

Notes:

• We recommend providing as many validated (correct) values as possible.
• Not providing a correct value of a field means the predicted value is incorrect, unless there is no predicted value.
• Field names are case sensitive and may only occur once in the CorrectValues collection.
• CorrectValue values are formatted as strings using the following formats:
  • Date: ISO 8601 format, e.g. “2019-01-02T00:00:00.0000000”
  • Number: “.” is used as decimal separator, no thousand separator
  • TaxLine’s: “{tax amount};{tax rate};{base amount}”, e.g. “21.00;0.21;100.00”
• After providing feedback, a model must be retrained to let the model take advantage of the new training data.

Training a model

You can train a model using POST /public-api/v1/air/model/train. Training is performed asynchronously and the training time depends on the amount of training data. A minimum of ~25 validated operation results is required before training is possible.

Using POST /public-api/v1/air/model/list (and checking the fields lastTrainingTime and isTrainingScheduled) you can verify if training is finished and has succeeded.

Data type value formatting

Extracted values are encoded as strings using the formats described in the table below.

Data type	Format	Example value
Date	ISO 8601 format	“2019-01-02T00:00:00.0000000”
Number	“.” is used as decimal separator, not as thousands separator	“12345.12”
Boolean	“True” or “False”	“True”

Limits and quotas

Supported document types	.pdf, .docx, .doc, .xlsx, .xls, .eml, .jpg, .jpeg, .png, .bmp
Supported legislations*	nl, gb, de, be, pl, fr, es, usa
Supported document cultures	nl, en, es, fr, de, pl
Max. document file size	25 MB (after base64 encoding)
Max. document dimensions	10.000 x 10.000 pixels
Max. document pages	No limit, but at most 50 pages are processed
Operation result lifetime	48 hours
Max. number of excluded feature values	50
Max. number of ML models	50**
Minimum time between model training operations	2 * average training time from the last 10 training operations

* Legislations are used for tax amount extraction only.

** Support can increase this limit on request.

Data storage

• Raw input documents are deleted when a process document operation finishes.
• If no custom model is used, operation results are deleted ~48 hours after the operation was finished.
• If a custom model is used, operation results and training data are stored until manual deletion of the model.

Billing

• The AIR API is available in all Zenvoices subscriptions (including Lite).
• One transaction is charged per five pages, with a maximum of ten transactions per document.
• Purchasing transaction bundles allows you to save up to 73% on transaction costs.
• See our terms of use and pricing page for transaction pricing and more information.

Financial transactions

This API allows you to list financial transactions and get financial transaction details.

Inbox

This API allows you to upload documents to the inbox of an administration.

Users

This API allows you to list users and get user details including permissions.

Support & SLA

• Chat/mail/phone support is included in all Zenvoices subscriptions.
• Please refer to the Zenvoices help centre for support availability and contact information.
• Our service level agreement applies.

Changelog

• 23-5-2022: increased AIR API max document file size from 10 MB to 25 MB, remove image limit of 4 MB and increased max. document dimension size from 3200 x 3200 to 10.000 x 10.000 pixels.
• 19-3-2022: changed rate limit from max. 10 request per second to max. 10 requests per second per endpoint.
• 14-12-2021: fixed inbox documents attachment not being visible after uploading an inbox document.
• 02-09-2021: added the ability to sort lists by specifying the new Sorting parameter.
• 09-07-2021: changed AreAllAdministrationsGranted field value from user to global level (i.e. also considering role permissions) in endpoint GET /public-api/v1/user/{userId}.
• 30-06-2021: fixed incorrect values of GrantedAdministrationIds field in endpoint GET /public-api/v1/user/{userId}.
• 11-06-2021:
  • Added users API
  • Added accounting systems API
  • Added downloadUrl property to FinancialTransactionAttachmentDto (GET /public-api/v1/financialTransaction/{financialTransactionId})
• 12-05-2021:
  • Added totalCount property to the response of end points that support paging.
  • Added enabledFeatures property to the respone of end point GET /public-api/v1/administration/{administrationId}
  • Fixed administration filter issue of end point POST /public-api/v1/administration/list
• 04-05-2021: changed response date formatting of AIR end points to ISO 8601
• 29-04-2021: initial version