The purpose of this manual is to describe Basware API integration capabilities for Master data imports and Purchase-to-Pay integration scenarios.  It contains process-level instructions, end-to-end data flows, as well as recommended practices for implementation and debugging.

Basware API is a REST API available through web service calls. JSON data format is used in the message payloads.

Basware API integrations are available for the following Basware end-systems.

  • Basware Network
  • Basware Purchase-to-Pay
  • Basware Supplier Management


P2P APIs are available through the following regions: Europe (EU), USA (US) and Australia (AU). APIs will be set up in the same region as your P2P system. Separate environments are available for test and production systems. 



List of available Purchase-to-Pay APIs

The following APIs are available for transferring invoices to accounting,  importing master data, user data and external purchase orders for invoice matching,  as well as for importing and exporting data to and from P2P Purchase. 

Importing master data Available Basware systems
AdvancedValidations Import invoice coding row validation rules from ERP P2P
Accounts Import accounts from ERP P2P
CostCenters Import cost centers from ERP P2P
ExchangeRates Import exchange rates from ERP P2P
GenericLists Import additional coding dimensions from ERP P2P
PaymentTerms Import payment terms from ERP P2P
Projects Import projects from ERP P2P
TaxCodes Import tax codes from ERP P2P
Vendors Import vendors from ERP P2P, Supplier Management
Importing user master data  
Users Import users

P2P, Supplier Portal, Supplier Management, Reporting, CloudScan 3.0 (available Q1/2021)

ApplicationGroups Control per-application log-in access (assigned to users). P2P, Supplier portal, Supplier Management, Reporting, CloudScan 3.0 (available Q1/2021)
AdvancedPermissions Import user approval rights information P2P
Importing external purchase orders for invoice matching  
MatchingOrders Import order header data into matching  P2P (AP Automation)
MatchingOrderLines Import and update order lines and goods receipts into matching P2P (AP Automation)
Importing and exporting procurement data for P2P Purchase  
PurchaseRequisitions Import purchase requisitions to P2P Purchase from an external system P2P (Purchase)
PurchaseOrders Import Purchase Orders to P2P Purchase from an external system P2P (Purchase)
Goodsreceipts Import goods receipts to P2P Purchase from an external system P2P (Purchase)
Contracts Import contract metadata to P2P Purchase from an external system P2P (Purchase)
ExportedPurchaseOrders Export purchase orders and GR's from P2P Purchase P2P (Purchase)
ExportedPurchaseRequisitions Export purchase requisitions from P2P Purchase P2P (Purchase)
Transferring approved invoices to accounting  
AcccountingDocuments Prebook invoices or transfer approved invoices to accounting system  P2P (AP Automation)
Acknowledge Mark invoice as fetched P2P (AP Automation)
PrebookResponse  Mark invoice as prebooked in accounting system P2P (AP Automation)
TransferResponses Mark invoice as transferred to accounting system P2P (AP Automation)
PaymentResponses Update invoice payment date P2P (AP Automation)
Retrieving API request status / errors
RequestStatus (new API) Check target system status of sent requests. Asynchronously returns success and error messages from target systems. Replaces errorFeedbacks API.  P2P, Supplier portal, Supplier Management, Basware Access
ErrorFeedbacks Error handling. Returns errors asynchronously from Basware receiving systems. P2P



Supported methods for Basware APIs

API methods and fields

Detailed documentation for available methods and field sets for each API are described in the P2P API reference documentation. 

Basware APIs support the following methods.

POST - Adds or updates records. Clears existing data from omitted fields

POST method updates the record based on externalCode field. If no record is found with given externalCode, a new record is created. All fields are updated within the record. Existing data in fields is cleared before the update.

PATCH -  Updates records. Preserves existing data in omitted fields

PATCH method updates the record based on externalCode field. Difference to POST is that only fields included in the JSON in the request are updated. Data fields not explicitly included in the JSON request are left unchanged.

GET - Gets records from Basware API

GET method lists the records for a particular interface. Returned data contains all JSON fields and their values for the returned records. An externalCode can be specified as parameter to return data for only the specified record.

DELETE -  Deletes records from Basware API

DELETE method deletes records from Basware API. The records are deleted from API only. To delete the records also from the data receiving Basware systems, use the data deletion mechanisms provided by each of the Basware receiving systems.

Data update scenarios

Below is an illustration of system behaviour in various data update scenarios.

API data flow scenarios-1


Usage scenario 1: Import master data

Basware solutions require a set of master data that replicate the Customer’s business model in Basware. This data is required to enhance the processing of business documents and makes it possible to bring all, or suitable parts of the validation logic to Basware.

As best practice, master data should be maintained in one central place. This data nearly always sits in an organization’s main ERP system. Basware API is designed for importing master data to Basware services from your central master data store(s). Master data can be made available in all supported Basware services.

Posting and updating basic records

The following diagram illustrates data flow for posting master data, such as basic data records and user data, to Basware API.

This is applicable for the following entity types (APIs): Accounts, AdvancedPermissions, AdvancedValidations, ApplicationGroups, Contracts, CostCenters, ExchangeRates, GenericLists, PaymentTerms, Projects, PurchaseRequisitions, PurchaseOrders, GoodsReceipts, TaxCodes, Users, Vendors.

POST operation must be used when first sending the record to Basware API. Records can be updated using both POST and PATCH operations. Basware recommends using POST operation to also update the records for most cases. PATCH may be more suitable when, for example, the sending system provides only the changed fields within the modified record.

Note that GenericLists API can be used to populate several different lists. The list key needs to be specified as additional parameter for this API.




Usage scenario 2: Import external purchase orders for Order Matching

In order matching a purchase order, purchase order line, or a goods receipt is linked to an invoice or invoice line. Basware API supports importing external Purchase orders from customer systems to order matching. Purchase orders, purchase order lines and goods receipts can be imported and updated using Basware API.

These orders need to be fully processed, approved, and marked received in external systems. These orders are called matching orders and they are used only for automatic matching to received invoices. Creating, approving and sending orders can be also done in Basware P2P using "Purchase" module, which has another set of APIs to integrate the purchasing process with external purchasing systems (see section "Usage scenario 4: Import and export procurement data").

Posting and updating matching orders

The following diagram illustrates data flow for transferring and updating order data for use in invoice matching. Purchase orders from external systems are received through the MatchingOrders (order headers) and MatchingOrderLines (order lines and goods receipts) API entity types.

Order header needs to be received before the order lines are sent. Both order headers and order lines can be updated through API when they are changed, for example when changing requested delivery date or when items have been received.            



 Validations applied in Basware API:

  • NetSum and grossSum must have a same sign within an object. Example: if an order line has a postive netSum like 100,00 EUR, the grossSum, if defined, must be equal or more than zero.
  • Sum for a blanket purchase order line(matchingOrderLines.matchingMode= 2) must be positive(matchingOrderLines.netSum=>0)
  • Quantity for a blanket purchase order line(matchingOrderLines.matchingMode= 2) must be one(1). ​
  • Quantity for a purchase order line must be higher than zero(matchingOrderLines.quantity >0)​
  • A blanket purchase order line(matchingOrderLines.matchingMode= 2) cannot require receipts(matchingOrderLines.isReceiptBasedMatching= true, matchingOrderLines.isReceiptBasedMatching= true)

Validations applied in Basware P2P:

  • A purchase order line that has been already matched, cannot be deleted (matchingOrderLines.isDeleted=true).
  • A purchase order line with positive total(matchingOrderLines.netSum=>0) that has been already matched, cannot be changed to have a negative total(matchingOrderLines.netSum<0)
  • A purchase order line with negative total that has been already matched(matchingOrderLines.netSum<0), cannot be changed to have positive total(matchingOrderLines.netSum=>0)
  • A purchase order line with isService = false that has been already matched, cannot be changed to be a service purchase order line(matchingOrderLines.isBlanketOrderLine= true)
  • A purchase order line that NOT require goods receipts(matchingOrderLines.isReceiptRequired= false) and it has been already matched, cannot be changed to require goods receipts(matchingOrderLines.isReceiptRequired= true)
  • A purchase order line that requires goods receipts(matchingOrderLines.isReceiptRequired= true) and it has been already matched, cannot be changed NOT to require goods receipts(matchingOrderLines.isReceiptRequired= false)
  • A purchase order line that requires goods receipt based matching(matchingOrderLines.isReceiptBasedMatching= true) and it has been already matched, cannot be changed NOT to require goods receipt based matching(matchingOrderLines.isReceiptBasedMatching= false)
  • A goods receipt that has been already matched, cannot be deleted(matchingOrderLines.goodsReceipts.isDeleted= true)
  • A goods receipt with positive total(matchingOrderLines.goodsReceipts.netSum=>0) that has been already matched, cannot be changed to have a negative total(matchingOrderLines.goodsReceipts.netSum<0)
  • A goods receipt with positive quantity(matchingOrderLines.goodsReceipts.quantiy=>0) that has been already matched, cannot be changed to have a negative quantity(matchingOrderLines.goodsReceipts.quantity<0)
  • A goods receipt with negative total(matchingOrderLines.goodsReceipts.netSum<0) that has been already matched, cannot be changed to have a positive total(matchingOrderLines.goodsReceipts.netSum=>0)
  • A goods receipt with negative quantity(matchingOrderLines.goodsReceipts.quantiy<0) that has been already matched, cannot be changed to have a positive quantity(matchingOrderLines.goodsReceipts.quantity=>0)

Usage scenario 3: Prebook and transfer invoice to Accounting

Once an invoice has been approved in P2P, it is routed to AP/finance users for transfer to accounting. In this phase, the invoice and its coding data are transferred to an ERP system for payment. This phase can be configured to be completed automatically.  

Prebooking invoices and transferring approved invoices to accounting

Prebooking and transferring invoices from Basware P2P to accounting use AccountingDocuments API. The progress of both activities is shown in 'ProcessingStatus' field. 

Invoice is made available for transfer to accounting when it has been approved in Basware P2P. When an invoice is transferred in Basware P2P it becomes available for a GET operation in AccountingDocuments API with status 'WaitingForTransfer'.  When a transfer succeeded message is received, invoice status in P2P is changed from “Transfer in progress” to “Processed”.

Invoice prebooking is an optional feature that can be enabled if required. In prebooking invoice data can be made available in the AccountingDocuments API before the invoice is approved. Prebooked invoices require a prebookeResponse message from ERP system. When a prebooked invoice is approved in P2P it will be made available in the accountingDocuments API as an invoice 'WaitingForTransfer'. Invoices can can be sent for prebooking automatically based on configurable rules. Manual selection of invoices to be prebooked is not yet supported.  

Invoice transfer consists of the following steps

    1. Get invoice data from the API for prebooking (processing status: WaitingForPrebook)
    2. Post technical acknowledgement (optional, processing status changed to: PrebookInProgress)
    3. Post prebook succeeded / failed message (processing status changed to: Prebooked, PrebookFailed)
    4. Get invoice data from API for transfer (processing status: WaitingForTransfer)
    5. Post technical acknowledgement (optional, processing status changed to: TransferInProgress)
    6. Post transfer succeeded / failed message (processing status changed to: Transferred or TransferFailed)
    7. Post payment information (optional, processing status changed to: Paid)
Expand below sections for status diagrams of invoice transfer flow in accoutingDocuments API. These describe the available status transitions in 'processingStatus' field.

Below diagram describes the main flow in terms of invoice status transitions in AccountingDocuments API.



Below diagram describes the available statuses in exception situations. Some of the exception statuses are currently reserved for future use. These are in grey and there is no interaction path leading to those statuses at the moment. Retransferring an invoice from P2P will start the invoice process again as in the main flow above. Note: If a prebooked invoice is returned, prebook cancellation may need to be triggered in ERP system from 'WaitingToBeReturned' status. Most returned invoices are reprocessed and retransferred again to ERP.



The following diagram illustrates the data flow for retrieving prebooked or approved invoices (AccountingDocuments) from Basware P2P to accounting and handling related response messages.





Usage scenario 4: Import and export procurement data

This set of APIs is used to integrate Basware Purchase to external purchasing systems. These APIs are not used to import orders for matching. For matching please see Usage scenario 2: Import external purchase orders for Matching. Basware Purchase handles the procurement process, i.e. approving the order, sending it out to supplier, and creating the goods receipts. Orders created in Basware Purchase are automatically available for matching.

Procurement data integrations scenarios

    • Purchase Requisitions can be created through several different methods in Basware Purchase. Basware API currently supports importing purchase requisition data as a draft to a specified owner. The imported data is prevalidated by Basware Purchase before the creation of the draft can start.
    • Basware Purchase supports contract based purchasing. Contract metadata can be imported through Basware API.
    • Orders and goods receipts can be exported from Basware Purchase. Whenever the order status changes, the data in API is also updated.
    • Importing purchase orders, importing GRs
    • Exporting purchase requisitions.

APIs for importing procurement data:

    • contracts
    • purchaseRequisitions
    • purchaseOrders
    • purchaseGoodsReceipts

Importing procurement data is done in similar manner as master data imports. See Usage scenario 1: Import Master data for more details. 

APIs for exporting procurement data:

    • exportedPurchaseOrders
    • exportedPurchaseRequisitions


Exporting procurement data is done in a similar manner to invoice transfer (Usage Scenario 3: Prebook and transfer invoices to Accounting). Exported data is made available in the exportedPurchaseOrders API from where it needs to be retrieved. Export is confirmed by sending an acknowledgement response. The acknowledgement response is mandatory. Orders which have been acknowledged are marked as 'Exported' and can be filtered out from the get next request. 




Usage scenario 5: Error handling and monitoring

You can check request status from end-systems (which receive data asynchronously) through ‘requestStatus’ API. When you POST records to Basware API, the posted data contents are schema validated on API layer and then distributed asynchronously to one or more target system(s).

In case an error occurs when target system(s) process the record, it will be returned through 'requestStatus' API. This API can be queried to check status of a request POSTed to Basware API. Errors returned by target systems are typically data validation errors that cannot be validated on the API layer. Examples of such errors would be "Company not found in target system" or "Cannot resolve username 'JOHNSMITH' to a valid purchase requisition owner". You can choose to query only errors or also success' responses. Retrieving only the errors should be enough for most use cases. Success responses indicate that the request has been succesfully processed in all of the target systems. If this does not occur within three hours, an error response is returned.

There is also an older 'errorFeedbacks' API, which returns only errors from P2P ('success' responses are not available). The 'errorFeedbacks' API is likely to be deprecated at a later time. There will be a 12 months notice period before eventual deprecation. Currently both APIs are functioning side by side and are returning same errors.

Retrieving request status messages from requestStatus API

Do a GET to 'requestStatus' API in order to retrieve target system processing status(es) for a POSTed request. Most often the request status response will be available within less than one minute. There are some conditions, such as a heavy initial data loads, where this can take longer. If there is no response from a target system within two hours, the request is set to ’Error’ status automatically. Checking this is done hourly, so max time until timeout is just below three hours.

Request status is shown as 'error' if one or more of the POSTed records could not be imported to one or more of the target systems. Note that you need to query the API separately for both 'success' and 'error' statuses. If parameter 'status' is not used in the GET requestStatus query, the API defaults to returning only messages which have received 'error' status. Basware recommends following ways to programmatically query the API.

Option 1: GET by status + acknowledge

  1. Get by statuses: 'error', 'success'.
    • This needs to be done in two GET requests.
  2. POST acknowledge for all requestIds (to which status response is received)
    • Acknowledged status responses are no longer offered on the next GET request.
    • Acknowledging changes the status: 'Error' -> 'AcknowledgedError', 'Success' -> 'AcknowledgedSuccess'.
  3. Repeat from step 1.

Option 2: GET by lastUpdated timestamp.

  1. GET with 'lastUpdated' timestamp
    • Include a stored 'lastUpdated' timestamp in GET request. Get by statuses: 'error', 'success'.
    • This needs to be done in two GET requests.
  2. Store the 'lastUpdated' timestamp locally.
    • Store the latest 'lastUpdated' timestamp separately for 'error' and 'success' statuses.
  3. Repeat from step 1.

Option 3: Get by requestId

  1. Save the returned requestId when doing a POST/PATCH request to Basware API
    • RequestId is returned as a header parameter in response message.
  2. Query the API using the requestId until a response is received.

Basware recommends doing GET requestsStatus 1 minute after sending a request. If several requests are sent over time, you can do GET requestStatus once a minute until the last request has been sent. It's also a good practice to additionally poll requestStatus API every 10..60 minutes to receive responses for potentially long-running requests. If status responses to all request have been received, this polling can be stopped until a new request is sent to Basware API.



[Legacy] Retrieving error messages from errorFeedbacks API

Note: The 'errorFeedbacks' API has been replaced by 'requestStatus' API and is likely to be deprecated at a later time. There will be a 12 months notice period before eventual deprecation. Currently both APIs are functioning side by side and are returning same errors.

In case an error occurs while using an API an error message is returned either in the API response message or through the ErrorFeedbacks API.

Errors from data validation in Basware API are returned immediately in the API response. These are mainly errors resulting from data structure validation and simple validations on data values.

Errors occurring when data is distributed from Basware API to the receiving Basware systems are returned asynchronously through the ErrorFeedbacks API. These include errors from validations performed in the receiving systems.

The following diagram illustrates data flow for receiving error messages.


Recommended practice is to query the errorFeedbacks API using the timestamp of the last error that has been retrieved. This will return any new errors that have occurred since the last time errors have been fetched. Errors will become available in the API at the same time as the receiving Basware systems process data. Most requests will be processed within 60 seconds. If there is considerable load errorFeedbacks will be available only after the receiving Basware systems have finished processing the data.



Usage scenario 6: Import companies

Importing companies is a network-only usage scenario (companies cannot be imported to P2P). Companies are imported through the 'companies' API. The sequence of API messages is same as when posting master data records.

The company identifier type (field identifiers.schemeId) needs to be specified from available values. Please expand the element under the flow diagram for a table of available values.




Global identifiers

SchemeId Name Description Type External link Alternative name(s) Alternative form(s)
DUNS DUNS A proprietary system developed and managed by Dun & Bradstreet General   - -
EMAIL-RFC2822 Email Email address General   - -


Global Location Number (GLN)   General   - -
IBAN IBAN Bank account in IBAN format General   - -
ISO6523-ACTORID-UPIS ISO 6523 Globally unique identifiers based on ISO 6523 and PEPPOL. Prefixes denote issuing authorities (ICD) and may be known by regional names such as OVT in Finland (prefix 0037) with format of <prefix>:<organization identifier> or <prefix><organization identifier> General - -
UNKNOWN   No known schemeId -   - -


Regional identifiers

SchemeId Name Description Type External link Alternative name(s) Alternative form(s)
EU:VAT European VAT A value added tax identification number, or VAT identification number (VATIN), is an identifier used for value added tax purposes. Tax VAT, AT:VAT, BE:VAT, BG:VAT, CY:VAT, CZ:VAT, DE:VAT, DK:VAT, EE:VAT, EL:VAT, ES:VAT, FI:VAT, FR:VAT, GB:VAT, HR:VAT, HU:VAT, IE:VAT, IT:VAT, LT:VAT, LU:VAT, LV:VAT, MT:VAT, NL:VAT, PL:VAT, PT:VAT, RO:VAT, SE:VAT, SI:VAT, SK:VAT Country VAT code specific


Country specific identifiers

SchemeId Name Description Type External link Alternative name(s) Alternative form(s)
AT:ORGNR Austrian Firmenbuchnummer Organization number in Austria is a unique combination of 6 digits and a letter. Business Identifier - -

Australian Business Number (ABN)

An ABN (Australian Business Number) is a unique number issued by the ATO (Australian Taxation Office) to all entities that are in business.

Business Identifier

ABN ISO (some can be converted to AU:ACN)
AU:ACN Australian Company Number (ACN) ACN (Australian Company Number) Business Identifier AU:CAN, AU:ORGNR ISO
AU:TFN Australian Tax File Number (TFN) A Tax File Number is a personal reference number used in tax and super systems. Tax File Numbers are issued by the Australian Taxation Office. Business Identifier TFN -
BE:KBO Belgium KBO (CBE) The KBO nummer is a unique 10 digit identifier issued to companies by the Kruispuntbank van Ondernemingen. Business Identifier BE:ORGNR, BE:CBE BE:VAT, ISO
CA:BN Canadian Business Number A Business Number (BN) is a unique identification number that identifies a business in Canada. Business Numbers are issued by The Canada Revenue Agency. Business Identifier

- -
CA:GST Canadian GST The Goods and Services Tax (GST) is a value added tax in Canada. Tax - -
CA:VAT Canadian VAT Canada does not use a VAT system, but bases all taxes on BN. Tax

- -
CH:ORGNR Swiss Unternehmens-Identifikationsnummer (UID) Every company active in Switzerland receives a uniform corporate identification number (UID). Business Identifier - -
CH:VAT Swiss VAT A value added tax identification number, or VAT identification number (VATIN), is an identifier used for value added tax purposes. Tax   - -
CN:BRN Chinese 统一社会信用代码 (Business Registration Number or Unified Social Credit Code) A unique company identification and tax number (TIN) for all Chinese mainland registered companies.


- .
CZ:ORGNR Czech Republic IČO The IČO of company Identification number is an 8 digit code (older organizations may be composed of 6 digits). Business Identifier - -
DE:ORGNR German Steuernummer Steuernummer is a unique identifier issued to each taxable individuals or entities by the German Federal Central Tax Office. Tax - -
DK:CVR Danish CVR The CVR nummer is a unique identifier issued by the Central Government Register. The CVR provides financial information, mission information, company filings, information about management, and corporate governance. Business Identifier DK:ORGNR, CVR -
EE:ORGNR Estonian Organization Number Company registry code in Estonia is a unique 8 digit number. Business Identifier - -
ES:CIF Spanish Certificado de Identificación Fiscal (CIF) CIF (Certificado de Identificación Fiscal) is the tax identification number for companies issued by the Registro Mercantil Central. Tax ES:ORGNR -
ES:NIF Spanish Número de identificación fiscal (NIF) NIF (Número de identificación fiscal), or Tax Identification Number, or Tax File Number, is used to identify a taxpayer in Spain. Tax - -
FI:Y-TUNNUS Finnish Y-Tunnus A Business ID ("Y-tunnus" in Finnish) is a unique eight-digit number issued to companies by the Finnish Patent and Registration Office. Business Identifier FI:ORGNR, Y-TUNNUS FI:VAT, ISO
FR:SIRENE French SIRENE A SIREN number is a unique French business identification number issued by the INSEE. Business Identifier FR:ORGNR ISO
FR:SIRET French SIRET SIRET codes are given the establishments and facilities of French businesses and nonprofit associations. Business Identifer - -
GB:UTR United Kingdom Unique Taxpayer Reference (UTR) A UTR (unique taxpayer reference) number is a 10-digit number completely unique to each and every UK taxpayer. Business Identifier UTR -
IE:ORGNR Irish Company Registration Number Company registration number in Ireland is a unique 6 digit number. Business Identifier - -
IN:GSTIN Indian GST Tax Identification Number (GSTIN)

Under the GST regime, all registered taxpayers are consolidated into one single platform for compliance and administration purposes and are assigned registration under a single authority.  All of these businesses will be assigned a unique Goods and Services Tax Identification Number (GSTIN). 

Tax - -
IT:FISCALE Italian Codice Fiscale The Italian Fiscal Code Card ("Codice Fiscale" in Italian) is an identification number for companies issued by the Italian Tax Office. Business Identifier IT:ORGNR -
IT:IPA Italian Indice della Pubblica Amministrazione (IPA) An index of public administration (Indice della Pubblica Amministrazione - abr. IPA) is an identifier given by the Public Admininstration. Business Identifier - -
LI:VAT Liechtenstein VAT A value added tax identification number, or VAT identification number (VATIN), is an identifier used for value added tax purposes. Tax   - -
MX:VAT Mexican VAT A value added tax identification number, or VAT identification number (VATIN), is an identifier used for value added tax purposes. Tax

- -
MY:GST Malaysia GST The Goods and Services Tax (GST) is a value added tax in Malaysia. Tax - -
NL:KVK Dutch KvK The KvK number is a unique identifier allocated by the Dutch Chamber of Commerce. The KvK-nummer must contain 8 digits. Business Identifier NL:ORGNR ISO
NO:ORGNR Norwegian Organisationsnummer A unique nine-digit identifier for organizations issued by the Brønnøysund Register Centre. Business Identifier   NO:VAT, ISO
NO:VAT Norwegian VAT A value added tax identification number, or VAT identification number (VATIN), is an identifier used for value added tax purposes. Tax   - ISO
PL:KRS Polish Krajowy Rejestr Sądowy (KRS) The object of the National Court Register is to provide readily-available and reliable information on the legal status of a registered entity (The Central Information of the KRS), the material elements of its financial condition and the manner of its representation. Business Identifier KRS -
PL:REGON Polish REGON Organization number in Poland is a unique 9 digit number. Business Identifier PL:ORGNR, REGON -
PT:NIF Portuguese Número de Indentificação Fiscal (NIF) Tax Identification Number ("Número de Indentificação Fiscal", or "NIF" in Portuguese), also referred to as the Tax File Number, identifies a taxable entity in Portugal. Tax PT:ORGNR PT:VAT, ISO
SE:ORGNR Swedish Organisationsnummer Organization Number ("Organisationsnummer" in Swedish) is a 10 digit identifier for organizations issued by the Bolagsverket. Business Identifier - GLN, ISO
SK:ORGNR Slovakian IČO The IČO of company Identification number is an 8 digit code (older organizations may be composed of 6 digits). Business Identifier - -
GB:ORGNR United Kingdom Company Registration Number (CRN) Company Registration Number is a unique identifier issued by the Companies House upon the registration of a company. Business Identifier UK:ORGNR -
UstidNr German Handelsregisternummer Handelsregisternummer is a unique indentifier issued by the Commercial Register ("Handelregister" in German) to a legal entity. Business Identifier    
US:TIN United States Tax Identity Number (TIN) A Taxpayer Identification Number (TIN) is an identification number used by the Internal Revenue Service (IRS) in the administration of tax laws. It is issued either by the Social Security Administration (SSA) or by the IRS. Tax TIN -


Usage Scenario 7: Import users

Users can be imported through the 'users' API. It is possible to import user(s) to any of the following Basware applications: Purchase-To-Pay (P2P), Supplier portal (network), Supplier Management (network), Network, CloudScan 3.0 (available Q1/2021). The log-in-to-application rights are managed through both 'users' and 'applicationGroups' APIs.

Before importing users, you need to have one or more application Group(s) set up for the users. Application groups provide log-in access to applications when applicationGroups are assigned to users. Each user contains a section specifying which applicationGroups the user has access to. After the application groups are set up, POST user(s) while specifying their assigned applicationGroups.

If some of your end users require access to more Basware systems than other users, you will need to define multiple applicationGroups. An example of this would be access to P2P and Vendor management for some users while most users access only P2P. If you need to define invoice approval rights for users on coding row level, you can also import these using advancedPermissions API.

Note: If you are not importing users from scratch but have an existing P2P tenant where users have already been created, it is still possible to move user maintenance to Basware API. See FAQ article "Can I migrate user maintenance to users API on an existing P2P tenant" for what needs to be taken into consideration. 



Common considerations when using Basware API

Please take the following into account in order to achieve smoothly running integrations.

Records are identified for update based on ‘externalCode’ field value

ExternalCode field is present in all record types. This field is used to identify the record to be updated and must be unique per record within an interface (single Account, Cost Center, etc.). More specifically, it must be unique within an Entity Type (Accounts, CostCenters, etc).

Exception to this is GenericLists, where the externalCode must be unique within the target list (specified by the ‘listKey’ parameter).

Maximum length of the externalCode is 36 characters – this needs to be maintained in cases where externalCode is concatenated from other key values, such as [companyCode]_[AccountCode]. The max length of these values combined must not exceed 36 characters.

Inactivating records is done by updating the record

Records are inactivated by updating the record with field ‘active’ = ‘false’. There is no explicit delete (or delete/insert) functionality.

Changed records are forwarded from Basware API to receiving Basware systems

To improve end-to-end integration throughput, received data is compared record-by-record to current data stored in the Basware API. Only records with changed data (compared to what is already in Basware API) are forwarded to receiving systems.

Basware API is primarily designed to receive incremental data changes.  It is still possible to send a full data set (such as full list of suppliers) once per night.

GET method returns the latest version of data posted to Basware API

Changes made manually to master data, for example through user interfaces, are not reflected in returned results. GET is mainly intended as a tool to check what has been posted to Basware API.

Number of records per message is limited per API

Consecutive API calls are needed for processing large amounts of records.  The record limit varies by endpoint. It is 100 for AccountingDocuments, MatchingOrderLines and PurchaseRequisitions, and 500 for everything else. Please distribute the payload over multiple requests to stay below the respective limits.

Please send the ‘x-amz-meta-continuationtoken’ parameter value returned in previous GET response header as parameter in the GET request header in order to retrieve the next batch of items.

API responses make use of HTTP redirects

Programs using Basware API need to handle redirects either at the application layer or the HTTP layer. Please verify all HTTP request headers are correctly 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 (new fields may be added to Accounts, Vendors, AccountingDocuments, etc). Please make sure your API client is configured to read data from records returned from API using named JSON fields and does not assume the fields come in a predefined sequence of elements.

Basware also reserves the right to send only those fields in API responses, where the field value is not null. Please make sure your API client checks whether the field exists in the received JSON before attempting to parse it’s contents.

The above kinds of changes are considered minor (non-breaking) changes and may be performed by Basware upon discretion at any time. 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 (‘v2/accounts’ instead of ‘v1/accounts’, etc)

Automatically populated fields in API

The following fields are automatically populated and should be omitted with POST and PATCH requests. They will be visible with GET requests and therefore are present in API schema definitions.

  • LastUpdated (All APIs)
  • Buvid (Vendors)


Authentication and access rights


Basware API uses basic HTTP authentication to authenticate API clients.

All communication is secured by using the HTTPS protocol (HTTP over TLS). You must make all API requests over HTTPS. API requests made without authentication will fail.

Access rights

API user access rights can be set per API endpoint. This controls what the user can do when interacting with Basware API.

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 reporting integration, which for example is only allowed to GET records

The available access rights are 1) "Read", 2) "Write" (=read+write), 3) "Delete" (read+write+delete). If no restrictions are specified API users will have full access (read+write+delete) to all APIs.



API response codes

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

  • 200/OK: Credentials validated, task executed successfully
  • 404/Not Found: Credentials validated, that particular data item does not exist (e.g. unknown Account)
  • 403/Forbidden: Credentials invalid
  • 405/Method Not Allowed: Typically occurs on POST Acknowledge, when the invoice has been already acknowledged. Each invoice can be acknowledged only once. 
  • 411/Length Required: URI is not correct, check for typos (case-sensitive). This usually occurs on POSTs.
  • 502/Bad Gateway: URI or endpoint does not exist, check for typos (case-sensitive). This usually occurs on GETs



API Versioning

Every time there is a backwards-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 v1.

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 your API client accepts new non-mandatory fields.



Fair use practices

Data import APIs

Data import APIs are intended only for importing data from Customer systems to Basware systems. Data imports are one directional, APIs will not reflect any changes done in Basware P2P.

Main use cases

  • Import new data entities (Method: POST)
  • Update existing data entities (Method: PATCH/POST)


Development phase / Supporting use cases

  • Getting data entities by external code (Method: GET) – This use case is mainly intended for development phase usage. Not to be used as part of production usage.
  • Deleting data from API layer – This use case is mainly intended for development phase usage. Not to be used as part of production usage.


Posting all entities vs changed entities

Best practice is to update entities one by one as they change as opposed to batch operations. If batch operation (posting all entities, not only changed ones, every time) is used then that should be done infrequently. Optimal frequency depends on how many data entities there are in total and should be discussed with Basware especially if there are very high number of entities


Invoice transfer APIs

Invoice transfer APIs are meant for transferring invoice data to ERP system when an invoice is ready for payment. The process includes polling the AccountingDocuments API for new invoices, fetching invoices and posting transfer and payment responses.

Polling for invoices that are ready for transfer

  • GET with status ‘ReadyForTransfer’ from AccountingDocuments API
  • It is recommended to use one polling process only to avoid duplicate requests
  • Polling frequency best practice is once per minute


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. Please ensure you have retry mechanisms in place to handle any failed requests.  

We may temporarily or permanently block access if you are calling the API too frequently or 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.

Update frequency for Matching Order Lines

  • Do not POST or PATCH updates to the same MatchingOrderLine more often than every 10 seconds.


Release notes

Release notes are updated after API release to production. 

Release to production API Change category Notes Type
20.8.2020 v1/matchingOrderLines Data validation change Ignore deleted goods receipts when validating PO line quantities Bug fix
20.8.2020 v1/Users Other Password field is no longer returned in API responses Bug fix
17.9.2020 v1/vendors New fields Added new non-mandatory fields vendorClass, deliveryLocation and orderingMessageLanguage New feature
17.9.2020 v1/errorFeedbacks Other ErrorFeedbacks API returns messages in correct order when not using lastUpdated -parameter Bug fix
1.10.2020 v1/purchaseGoodsReceipts Data validation change

Validate correct set of field are posted for both standard and reverse GRs.

New validation: If field 'referenceGRDocumentExternalCode' doesn’t have a value, then:

  • All of 'referenceGRLineExternalCode' -fields must not have value
  • All 'receivedQuantity' fields must be positive
New feature
19.10.2020 - Swagger update

Updated Swagger documentation

  • Revised Swagger documentation for Purchasing APIs.
  • Revised existing Swagger documentation based on user feedback
  • Improved documentation of error responses from API calls and from errorFeedbacks
  • Added links to developer site JSON examples.
19.10.2020 v1/exportedPurchaseRequisitions New API Introduced new API for exporting purchase requisitions from Basware P2P. New feature
26.10.2020 v1/PurchaseRequisitions Data validation change Increased max number of purchase requisition lines from 100 to 200. New feature
07.12.2020 v1/vendors Data validation change Increased max length of 'groupName' field (in customFields block) to 500 chars.
New feature
07.12.2020 v1/users Data validation change Increased max length of 'externalGroupCode' field (in groups block) to 260 chars. New feature
14.12.2020 - Swagger update

Updated Swagger documentation

  • Usability improvements: Swagger page opens with API methods collapsed and 'Models' section is automatically expanded.
  • Improvements to descriptions
20.1.2021 - Swagger update

Updated Swagger documentation

  • Better example values for exportedPurchaseRequisitions, exportedPurchaseOrders and accountingDocuments APIs
  • Improvements to descriptions


20.1.2021 - Other

Made Basware APIs available in Canada region (

New feature
25.1.2021 v1/applicationGroups Data validation change

Added CloudScan to list of applications supported in applicationGroups.

New feature
3.3.2021 v1/requestStatus New API

Introduced new API for tracking request status in target systems, supporting both 'error' and 'success' responses.

New feature
17.3.2021 v1/genericLists Data validation change

'Inherit' field is no longer mandatory.

Bug fix
17.3.2021 v1/purchaseGoodsReceipts Data validation change

'lineReceivings' block is now mandatory. Added API validation as field is required by target system (P2P).

Bug fix
Release notes are available from 20.8.2020 onward.



Entity type      

Named structured types with a key. They define the named properties and relationships of a record. Examples: accounts, costCenters, matchingOrderLines.


Instances of entity types (e.g. account, opportunity).

Accounting system

Computer program used for keeping accounts. Commonly included in an ERP system as a module


Enterprise resource planning (ERP) is defined as the ability to deliver an integrated suite of business applications. ERP tools share a common process and data model, covering broad and deep operational end-to-end processes, such as those found in finance, HR, distribution, manufacturing, service and the supply chain.

Basware P2P

Basware Purchase-to-Pay, in this manual refers to Basware Purchase-to-Pay solution.

Basware AP Automation

Accounts Payable Automation solution. Part of Basware P2P. 

Basware Purchase

Basware Purchase solution. Part of Basware P2P.