Frequently Asked Questions

Find answers to Frequently Asked Questions

How should I generate externalCodes?

ExternalCodes for records in Basware API need to meet the following criteria:

  1. They must retain their value when updating records (else data updates will not work)
  2. They most not exceed the field max length (else the record will be rejected by Basware API).

Two common ways are 1) using UUIDs and 2) Concatenating the externalCode from other key values, such as SourceSystem_CompanyCode_PONumber_PORowNumber_GRNumber.

The UUIDmethod requires saving this guid to the sending system. The second "composite key" method may make integration debugging more straightforward and requires making sure the combined key does not exceed the max length for externalCode -field.

It's up to the customer implementation what is the best way to create them.

How should I implement error handling when using Basware API?

Please refer to the error handling section of Purchase-to-Pay API manual.

My data record did not go into P2P and I got no errors. How should I debug?

Please check the errorFeedbacks API. Note that specific kinds of errors can take some minutes to become available in errorFeedbacks API due to internal retry logic. Try to use GET errorFeedbacks with just daterange search, setting the date to one day before your expected error (in case of timezone differences). If this does not resolve your issue, please contact Basware support.

If you send the exact same record again to API, it will not get updated into P2P as the data in API has not changed, even if the record is still missing from P2P. Try to modify the record slightly and send it again. Then API will send the record again to P2P and other target systems.

How can I clear existing user groups when updating users through API?

There is a setting in P2P admin, settings section called "Delete existing user groups when importing users". This setting needs to be enabled in order to clear existing user groups during import.

Can I import the same bank account twice (for example with different currencies)?

No, each bank account on the vendor needs to be unique.

I'm getting response code 405 'Method not allowed' when trying to send acknowledge to an invoice in accountingDocuments interface. Why?

This typically happens for invoices which have already been acknowledged. API allows acknowledging an invoice only once (unless it is retransferred from P2P). Already acknowledged invoices have 'processingStatus' = 'TransferInProgress'.

Paging continuation token does not seem to work for me when I'm trying to GET the next page of results. What should I do?

Please check that you are sending the x-amz-meta-continuationtoken parameter as a request header parameter. It does not work if it is not sent in header (for example in body).

The x-amz-meta-continuationtoken parameter is preconfigured in our Postman templates. Please try it out through postman using the preconfigured template, that should help spot the difference between how it is set up in the request sent by Postman and sending it in your HTTPS request.


I've deleted a record from target system and sent the same record again to API. Why did it not get created in my target system?

There is filtering in use for records which are sent unchanged from the last time the record was sent to API. Such records are not forwarded from API to the target systems. Please make a small change to the record manually (such as update the name) and resend, then it will pass the check in API. Alternatively, you can delete the record(s) from API and then post again.

Can I download a JSON schema validation file or a WSDL file for Basware API?

The swagger definition should serve you the same way as WSDL. You can download the swagger here  and then validate the messages against that. However, there is no JSON schema or WSDL file currently available.

I've updated a record in P2P and lost the changes when API has updated the same record. Is there a way to keep the changes I've made manually in P2P?

There is no way at the moment to keep changes made manually to records which are updated through the API. An exception to this is the vendors -interface, where some of the interface fields can be configured so API data does not overwrite existing data in P2p. This functionality to vendors -interface is planned to be released in Q3/2020.

Please find a way to update the data fully in your source system, alternatively you could consider creating a separate maintenance table for particular items - please discuss options for you specific scenario with your Basware consultant.

How do I set a vendor's default currency using Basware API?

The vendor's default currency is taken from field 'currencyCode' under paymentMeans block. Please make sure default = 'true' on the paymentMeans block with the default currency.

I have deleted data in an API interface using the delete command. Why is my data still in P2P?

The delete command deletes data from API only, you'll need to manually delete the data from the target system(s). The delete functionality is implemented mainly for manual clean-ups during / after development and does not support deleting the data all the way in target systems. Note in some cases the target systems also have restrictions on deleting the data if there are dependencies to it in other records in the system.

I have POSTed orders and see the data in P2P. Why are order header sums not displayed?

The order header sums are not imported through API. MatchingOrder APIs were built mainly for the new html5 based P2P user interface (Edge), which takes sums from order lines. In silverlight based UI (Workplace) the order sums are not available for API-imported orders. Matching is fully possible using both user interfaces for orders imported through API.

Can I migrate user maintenance to users API on an existing P2P tenant?

Yes you can. There are some things which need to be taken into account. The most important thing is to update user externalCodes in P2P to have same externalCode values that will be sent for each user through users API. This will enable users API to correcly identify existing users for update instead of creating new users instead. It is important to update existing users instead of creating new ones so the users preserve access to invoices they have processed and invoices they currently have in circulation.

User externalCodes can be updated either manually through the user administration -module in P2P or automatically with more direct access to the system. Basware consultants and delivery partners can update the externalCodes directly in P2P. Note that when importing users through API, the user will be available for a GET operation in users API only after the user has been POSTed to users API.

Please test this procedure in test environment to verify all the details are correctly in place before applying the same in a production environment.

I get message "default application group does not exist for customer" when posting users. What should I do?

You should create one or more applicationGroup(s). Application groups provide log-in access to applications when assigned to users.

Creating applicationGroup(s) can be done by a one-time POST applicationGroups -operation. The easiest way to do that is to use the preconfigured API call for POSTing applicationGroups. After the application group(s) are created, POST user(s) while specifying their assigned applicationGroup(s). See related P2P API manual article for more information.

Example message returned from users API in this situation:

"requestId": "e3361d63-bc8a-44a4-91f7-1ec4be706074",
"hasErrors": true,
"errors": [
"type": "VALIDATION",
"message": "The default application group does not exists for customer 123456"

I'm getting duplicate supplier additional data fields when I update existing suppliers. How do I remove the duplicates?

Handling supplier additional data fields (imported in vendors API 'customFields' block) in P2P is controlled by parameter 'DeleteAdditionalDataDuringSupplierImport' (in CMN_TENANT_SETTINGS in P2P).

When true, all existing values for supplier additional data fields are cleared before supplier is imported. When false, existing values are kept which can result in duplicate additional data -entries.

Most likely case is the parameter has incorrect value for your use case. Please check the parameter value and set it to 'true'.

Can I send payment/transfer/prebook responses through Basware API for invoices transferred to customer using Anyerp (which is another integration channel)?

This is an unsupported use case. The invoice needs to be present in accountingDocuments API for the responses to be updated to P2P. You will need to send the response information back through the same channel as was used for originally transferring the invoice.

I'm getting "Only one auth mechanism allowed" message when trying to GET invoices. How can I resolve this?

This typically occurs when GETting data from APIs that use redirects to allow large data payloads (accountingDocuments, exportedPurchaseOrders, etc) and the redirected request includes extra HTTP headers. For the redirected call, the 'Authorization' HTTP header must not be sent. The redirected call is using secure signed URLs with short expiration time.

In Postman this is controlled by a setting called "Follow Authorization Header", having default value false. Sometimes this header is copied from the original request by integration software used. Please adjust the settings of your integration software to not send this header on the redirected request.

I'm getting "Account not found" error from targetSystem: "Access" when posting users. How do I resolve this?

It looks like that you have MDD configuration in place for importing the data to Basware Access, but that you do not have a matching Basware Access account (one with the same customer id).

If you plan to use Access, you need to get Production to check the Access provisioning. If you don't plan to use Access, you need to remove or get removed the MDD configuration that synchronizes data to Access. In either case, please contact Basware's SaaS production team.

I need to reset the API status of an invoice which is in "WaitingForTransfer" status. What are my options?

There are the following options:

  • You can (manually) post a transfer failed / transfer suceeded response to API for the invoice.
  • You can manually cancel process for the invoice in P2P and retransfer it again from P2P
  • You can use the P2P transfer recovery scheduler task with parameter 'IncludeOpenAPIInvoices' = 'True'

Can I update voucher number through transferResponses API without yet indicating invoice transfer was succesful?

This scenario is currently not supported. API does updates only the comment in invoice history log when 'success' = 'false' on transferResponses API.

I'd like to provide basic data (vendors, account lists, etc) as an excel file and load that to P2P. Is this possible?

Basware has conversion tools from specific Excel templates to the JSON format natively used by Basware API. These can be used to load data to API.

Use cases include having relevant test data in the system before API build is complete on customer side or doing initial loads for data which is planned to be maintained manually in P2P. Please ask your consultant to provide these templates.

Is is possible to have Basware API system users with read-only access (or access to only a certain interface)?

Yes, this is possible. Please specify the permissions required for your API user and make a request to your consultant / CSM.

The users are created by SaaS production.

Can I use special characters such as % and / in record externalCodes?

You can, but this is not recommended as these are used as parts of an URL in the API's GET operations. If you would need to use these special characters they will need to be URL encoded whenever they are used as parts of a URL or used in query parameters.

"Import: User import failed due to an exception - Object reference not set to an instance of an object." I got this error message when posting users. How should I resolve this?

This error is due to the company on which you're importing the user not being marked as an administrative site in P2P. Make sure the the company to which you are posting the user is marked as an administrative site in P2P. When it is not, users cannot be imported to the company. We have logged an enhancement to return a clear error message also in this situation.

Can I make 1000 calls to matchingOrderLines API within an hour?

1000 calls in an hour should be fine. However, please avoid updating the same PO within ~5 seconds of the previous update. The interfaces currently lock the entire PO whenever just a part of it is updated. If a new update is received while the PO is locked it will go into delayed retries and it may take considerable time before all updates are processes.

What are the authentication methods supported by Basware API?

Basware P2P APIs support

  • Basic authentication over HTTPS
  • OAUTH2 (client credentials flow).

See Basware P2P API manual ('Authentication' -section) for more details.

Basware network APIs support basic authentication over HTTPS.

What does record status 'NotProcessed' mean in RequestStatus API?

Status 'NotProcessed' commonly occurs due to delta check. If the record contents has not changed since last time it was posted, API skips the record (as is nothing to update) instead of sending it to target systems. Below is an example requestStatus response JSON where this has occurred.