Basware Data Access API Manual

Basware data access API provides customers with efficient and secure access to their raw production data via API.

There are two tiers to the service:

1. Insights Essentials Data Access
2. Insights Pro Data Access

Insights Essentials Data Access contains an extract from the following data sets:

• Invoice data set: Contains invoices in Basware AP Automation. It includes header, line, and coding data sets.
  • IA_INVOICE
  • IA_INVOICE_ROW
  • IA_CODING_ROW
  • IA_INVOICE_ORDER_NUMBER
  • IA_INVOICE_DELIVERY_NOTE
• User data set: Contains users and the organizations that the users have access to in Basware AP Automation.
  • ADM_USER_DATA
  • ADM_ORGANIZATION_ELEMENT
• Supplier data set: Contains suppliers that have been imported or added in the Basware AP Automation.
  • ADM_SUPPLIER
• Purchase order data set: Contains purchase orders that have been imported or added in the Basware AP Automation.
  • OM_ORDER_DATA
  • OM_ORDER_ROW
  • OM_GOODS_RECEIPT
  • OM_CODING_ROW

In addition to the above data sets, the Insights Pro Data Access contains the following data sets:

• Invoice history data set: Contains actions that happened during the life cycle of the invoice in Basware AP Automation.
  • IA_ACTION_LOG
• Process data set: Contains process tasks that happened during the life cycle of the invoice in Basware AP Automation.
  • PE_PROCESS_TASK

Data access API approach

Data access API provides a mechanism to fetch the available extracts from the above list of data sets.

Each extract can have multiple data sets. Each data set file has a limit of 100K records. If the limit is exceeded, separate files will be created for that data set. These extracts are not runtime data from production, they are changes made to the data after a delta was previously created

Initial loads for both Insights Essentials Data Access and Insights Pro Data Access contain all documents from the production environment, aligned with the Basware Cloud Services data retention period. Initial loads are created when the service is activated.

Initial loads and deltas are retained for one year from the date of the creation of the extracts.

Initial loads and deltas can be downloaded fifty times. 

GET /v1/dataExtracts

• Includes an optional parameter "processingStatus" that can be used to filter only the extracts with processing status "WaitingForExport" or "Exported".
  • Possible values: WaitingForExport, Exported
• Returns a list of extracts for a tenant.
• Each extract item in the list contains:
  • id: ID of the extract
  • type: Type of the extract, "Initial" or "Delta"
  • startDate and endDate: Time range for extracted data
  • fileCount: How many files the extract contains
  • processingStatus: Is the extract already exported (downloaded) or not, "WaitingForExport" or "Exported"
  • extractDate: Date when the extract was done
  • extractName: Name of the extract configuration used for the extract

GET /v1/dataExtracts/{extract_id}

• Returns a list of file information related to a given extract ID.
• Each file information in the list contains:
  • extractId: ID of the extract where the file belongs to
  • tableName: Name of the table where the data in the file is coming from
  • fileName: Name of the file
  • downloadUrl: URL where the file can be downloaded

POST /v1/dataExtracts/{extract_id}/acknowledge

• Can be used to mark the extract as downloaded.

GET /v1/dataExtracts/specification/tableDefinition

• Can be used to get the specification of the content inside the downloaded extract ZIP files.

Format in the data extract zip files

During the provisioning of the data extract service, make sure that you specify the desired format for the data extracts in the ZIP files. Supported formats are JSON or CSV. 

Note: Formats need to be defined and agreed during the provisioning of the service and cannot be changed later.

Use GET to URL: https://api.basware.com/v1/dataExtracts. You will receive a list of available data extracts.

Use "id" from above list and use GET to URL: https://api.basware.com/v1/dataExtracts/{extract_id}. You will get information about the content of that extract ID and a URL to download it.

Based on the type available in the information you can decide if it is an initial load or a daily delta extract.

Initial load

If the "type" in the list of the extracts is "Initial", the extract is for the initial load. 

Initial load defines the data extracts that contain the data for all documents from your production environment, aligned with the Basware Cloud Services data retention period.

If you are a new customer and you are building the integration from day one, you do not need initial load. 

Daily deltas

If the "type" in the list of the extract is "Delta", the extract is for the daily delta. 

• Daily deltas are daily changes or changes from the last extractions. 
  • New documents
  • Any document status changes
• Delta is available for one year from the creation date. 
• Delta is created for each data set on a daily basis.
  • Customers must build continuous delta flows. For example, if a customer wants to have data for the whole week, they must get the delta for each day. 
• Delta is always a snapshot from the previous extract.

Acknowledge 

After you have downloaded the files from the extract, and if you do not want the already downloaded extracts to be shown again, you can use the following API:

Use POST /v1/dataExtract/{extract_id}/acknowledge with the following message to mark them acknowledged. The acknowledged extracts will not show up again when fetching the list of extract ids.

Requesting the data extract ZIP file specification

Use GET to https://api.basware.com/v1/dataExtracts/specification/tableDefinition. You will get a specification of the content inside the extracted ZIP file.

Consider the following to ensure smooth integration operations:

API responses use HTTP redirects

Programs using Basware API must manage redirects either at the application layer or the HTTP layer. Make sure that all HTTP request headers are accurately included in the redirected request (the second request after receiving a redirect), including HTTP standards such as Authorization and Date.

JSON parsing requirements for API clients

Basware reserves the right to introduce new non-mandatory fields to existing API data schemas. Make sure that your API client is configured to read data from records that are returned from API using named JSON fields, and that it does not expect the fields to always come in a predefined sequence of elements.

Basware also reserves the right to include only those fields in API responses where the field value is not null. Make sure that your API client checks whether the field exists in the received JSON before attempting to parse its contents.

The above types of changes are considered minor (non-breaking) changes and may be performed by Basware at any time at their discretion. Changes where, for example, a mandatory field is added or removed, or existing field names are changed, are considered major (breaking) changes and will be published under a new API version.

JSON parsing requirements for data extract ZIP files

Basware reserves the right to introduce a new field in the data extract ZIP file. Make sure that your integration is configured to read data from records that are returned in ZIP files using named JSON fields, and that it does not expect the fields to always come in a predefined sequence of elements.

CSV parsing requirements for data extract ZIP files

Basware reserves the right to introduce a new field in the data extract ZIP file. Make sure that your integration is configured to read data from records that are returned in ZIP files using named CSV fields, and that it does not expect the fields to always come in a predefined sequence of elements.

Authentication

Basware APIs support the following authentication types to authenticate API clients. You can choose the authentication type when requesting Basware to create your API user.

• Basic HTTP authentication
• OAUTH2 (client credentials flow)

All communication is secured using 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.

Using basic HTTP authentication

Basic HTTP authentication relies on passing username and password along with each API request. The username and password are encoded in the HTTP Authorization request header.

Using OAUTH2 authentication

Basware P2P APIs support the OAUTH2 client credentials flow. The client credentials flow works by first requesting an access token from a dedicated API endpoint /v1/tokens using a client ID and client secret (sent as Basic Auth header), then passing that token in subsequent API operations. This token is passed as a bearer token in the Authorization request header. You must specify the API operations permitted by the token when requesting the access token. Tokens have a limited validity time (default one hour), after which a new token needs to be requested. Token validity time can be specified while requesting the OAUTH2 credentials from Basware. The minimum validity time is five minutes and the maximum is 24 hours.

There is a separate swagger page for the APIs to retrieve OAUTH2 tokens. Most integration tools have built-in OAUTH2 support for both requesting an access token and using it in subsequent calls.

API operations permitted by an access token are called scopes. The scopes available are restricted by the access rights granted to API users. When returning the requested scopes Basware API will ignore any missing or misspelled scopes. Scopes must always be specified. For optimal security, it is recommended to request only the scopes necessary for each API operation during production use. Multiple scopes can be specified by separating them with a blank space.

Each scope in Basware API consists of API name + allowed operation. The following operations are available:

• 'read' operation grants access to GET operations.
• 'write' operation grants access to POST and PATCH operations.
• 'delete' operation grants access to DELETE operations.

Available scopes are listed below.

Scopes for the Data Extract API

• dataExtract.read
• dataExtract.write

Note that the scopes must be separated by a blank space. If you have copied and pasted multiple lines from the list above, remove the new line characters. The scope 'taskStatus.read' is necessary to check the status of long-running DELETE operations.

Make sure you have a mechanism to automatically fetch a new token when your existing token expires. This is especially important for long-running tasks, such as a large initial loads of matching orders, that may take more time than the maximum validity time of a token (24 hours). Basware API does not support refresh tokens. You must request a new token every time using client ID and client secret (same way as when getting the token for the first time).

API consumers can validate token signature using metadata from API endpoint:/.well-known/jwks.json. Each token returned by Basware API is signed by one of the public keys listed in the returned payload. The access tokens are returned as jwt tokens. Their contents can be viewed through jwt.io.

If you are currently using basic authentication and want to switch to using OAUTH2, you can request OAUTH2 authenticated API user credentials from Basware. You will receive new credentials. Your existing basic authentication API credentials will continue to work alongside the new OAUTH2 credentials. When you have completed the switch, request Basware to deactivate your previous API user credentials.

Access rights

API user access rights control what the user can do when interacting with Basware API. One user can be granted several kinds of access (read, write, delete) to several API endpoints. It is possible, for example, to have read access to AccountingDocuments and read+write access to Contracts on the same API user. You can request an API user with a combination of read/write/delete access to any of the APIs listed in this manual. If no restrictions are specified, the API users will have full access (read+write+delete) to all P2P APIs. Changes to API access rights will take effect within five minutes from making the change.

Available access rights are:

• 'read' grants access to GET operations.
• 'write' grants access to POST and PATCH operations.
• 'delete' grants access to DELETE operations.

For full access, all above rights mus be granted. Write alone does not grant access to GET operations and delete alone does not grant access to GET/POST/PATCH.

If the API user uses OAUTH2 for authentication, there are two levels of granting access. The first level is on the API user, specifying what access is granted overall for the user. The second level is controlled by the customer when requesting scopes on OAUTH2 access tokens. The scopes on the token determine which API operations are allowed when passing the token. If scopes are requested to API operations that are not granted to an API user, such scopes will not be granted through access tokens either.

Common scenarios where access restrictions are needed are:

• Restricting access for technical partners, who GET/POST data only to one API, such as Contracts.
• Restricting access for a reporting integration, which for example is only allowed to GET records.

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

• 200 OK: Credentials validated; task executed successfully.
• 400 Bad Request: Request data is invalid.
• 401 Unauthorized: Invalid credentials.
• 403 Forbidden: Requested data is not accessible.
• 404 Not Found: Requested data or endpoint not found.
• 422 Unprocessable Entity: Requested content cannot be processed.
• 500 Internal Server Error: Something unexpected happened.

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 Basware's technical support department that we are discontinuing support for a particular API version, you do not need to switch API versions. Basware will let you know at least 12 months in advance if an old API version is to be deprecated.

Major change

Major change requires changes from the API consumer before the new version can be taken into use. For example, a change to the 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. For example, adding a new non-mandatory field. Make sure that your API client accepts new non-mandatory fields.

Data access content change

Content in the data access ZIP file is independent of the API versioning. Additional fields can be added to the ZIP files. Make sure that your integration is able to adapt to the new fields. If the existing field names are changed or fields are removed from the data access ZIP file, the changes will be visible in the table.

Rate limits for APIs

The API platform has been built to scale up and down automatically. Sudden peaks in usage can potentially cause timeouts, as it may take a moment for the platform to scale up. Please avoid very high concurrency, especially when starting an integration flow. Make sure you have retry mechanisms in place to handle any failed requests.

Basware may temporarily or permanently block access if you are calling the API too frequently, or if you are requesting an unreasonable amount of data in a short time period. The limits should only affect scripts that are malfunctioning or attempting to make too many requests in parallel.

Release notes are updated after API release to production. 

Release notes are available from December 2022 onward.

Customer data: Data or material related to Customer's business submitted by Customer or its Affiliate, or on behalf of Customer or its Affiliate, to the Cloud Service.

Basware generated data: Meta data generated by the Basware Cloud Services from the service usage and the processing of the customer data. Meta data such as business document processing statuses and process automation KPIs.

Delta: Daily changes or updates in the data, particularly within a system or a dataset, compared to the previous extractions or snapshots. It is a measure of incremental changes that have occurred within a specified time frame, configured to be provided once a day.

Initial load: Data extracts that contain the data for all documents from your production environment, aligned with the Basware Cloud Services data retention period.

Extract: Extract contains multiple ZIP files for different data sets.