Basware SmartPDF API Manual

SmartPDF uses an intelligent algorithm to determine the layout of invoices, whether they are machine-readable or image PDFs. Leveraging advanced artificial intelligence (AI) technology and templates, SmartPDF converts PDF files into e-invoices quickly and with high quality. 

With our easy self-validation tool your team can easily handle exceptions and train the AI to extract data automatically. 

The purpose of this manual is to describe the Basware SmartPDF integration capabilities for PDF upload scenarios. It contains process-level instructions, end-to-end data flows, as well as recommended practices for implementation and debugging. 

Basware SmartPDF API is a REST API available through web service calls. JSON data format is used in the message payloads. SmartPDF APIs are available only in the EU region. Separate environments are available for test and production systems.

To upload the document with the SmartPDF API, you must have SmartPDF API credentials and a business unit specific email address configured in SmartPDF service. Both can be fetched from the Basware SmartPDF configuration tool. 

1. POST required metadata to the SmartPDF API documents endpoint. This will return a pre-signed URL together with the document identifier (bumId).
2. PUT the PDF file to the pre-signed URL returned in step 2 to upload the actual invoice document. 

Detailed documentation for available methods and field sets for each API are described in the SmartPDF API Swagger documentation. 

Authentication

Basware SmartPDF APIs support API access key authentication type to authenticate API clients. The API access key created in SmartPDF configuration tool and added the HTTP Authorization request header. 

All communication is secured with the HTTPS protocol (HTTP over TLS, TLS version 1.2 or later). You must make all API requests over HTTPS. API requests made without authentication will fail. 

SmartPDF API can be protected with IP address whitelisting in addition to the API access key. IP whitelisting is configured in Basware SmartPDF configuration tool.

The various response codes are outlined in the API definition per endpoint and method. Overall, API responses:

• 200 OK: Credentials validated; task executed successfully.
• 403 Forbidden: Invalid credentials.
• 400 Bad data: Data does not belong to the mentioned API schema.
• 502 Bad Gateway: URI or endpoint does not exist, check for typos (case-sensitive). This usually occurs on GETs.

Every time there is a backward-incompatible change to the API, a new major version will be released. This major version is part of the URL path. The current major version is v. 1.

Unless informed by our technical support department that we are discontinuing support for a particular API version, you do not need to switch API versions. We will let you know at least 12 months in advance if an old API version is to be deprecated.

Major change

Change that requires changes from the API consumer before the new version can be taken into use. This change would for example be a change to existing fields or adding new mandatory fields.

Minor change

Minor change is a new version of the API that is backward compatible and does not require changes from the API consumer. Minor change would consist of for example adding a new non-mandatory field. Please make sure that your API client accepts new non-mandatory fields.

Release notes are updated after API release to production.