Inhoud
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