Basware API Integration Research

Date: 2026-02-24 Status: Research complete (v2 — with Orcha-specific deep dive)

1. Summary — Capability Matrix

Verdict: Basware has a comprehensive, well-documented REST API with full CRUD on master data, bidirectional invoice workflows, document upload, and event-driven webhooks. This is a mature API surface.

2. API Landscape

API Products (6 distinct APIs)

Regional Endpoints

Authentication

• AP Automation API: OAuth2 client credentials flow OR Basic Auth over HTTPS
• Network APIs: Basic Auth only
• Vault APIs: Basic Auth only (TLS 1.2+)
• SmartPDF API: API Key in x-api-key header
• Credentials provided by Basware delivery consultant (not self-service)

Rate Limits & Fair Use

• ~1000 calls/hour is safe
• Avoid updating the same PO within ~5 seconds
• Records lock during update; rapid successive changes cause delayed retries
• Unchanged records (delta check) are silently skipped — not forwarded to target systems

Key Behaviors

• POST = create or full update (clears omitted fields)
• PATCH = partial update (preserves omitted fields)
• DELETE = removes from API layer only, NOT from target systems
• Most requests processed within 60 seconds, max ~3 hours before auto-error
• Asynchronous processing: POST returns 202, check RequestStatus for result
• externalCode field is the primary key for upsert logic

3. Write Capability Verification

Confidence: HIGH — Write capability is extensively documented and confirmed.

Evidence

1. Official docs explicitly state: "Data import APIs are intended only for importing data from Customer systems to Basware systems" — confirming one-directional write (customer → Basware).

2. POST endpoints are real writes, not disguised reads:

   • POST /v1/vendors → creates/updates vendor records
   • POST /v1/accounts → creates/updates GL accounts
   • POST /v1/costCenters → creates/updates cost centers
   • POST /v1/purchaseOrders → imports purchase orders
   • POST /v1/acknowledge → marks invoice as fetched (state change)
   • POST /v2/invoices/{bumId} → sends invoice into Basware Network
   • POST /v2/files → uploads file attachments
   • POST /v1/smartpdf/invoiceUpload → submits PDF for OCR processing

3. Full CRUD on master data: POST (create/update), PATCH (partial update), GET (read), DELETE (remove from API)

4. Invoice lifecycle write-backs: PrebookResponses, TransferResponses, PaymentResponses — all POST endpoints that update invoice state in Basware

5. FAQ confirms write concerns: "Manual changes get overwritten" by API updates — indicating API writes take precedence

4. iPaaS & Middleware Findings

Key insight: No major iPaaS has a pre-built Basware connector. This is consistent with Basware's enterprise positioning — their customers typically build direct API integrations or use XML/SFTP. The API itself is well-documented enough that middleware is unnecessary.

5. Alternative Channels

SFTP (XML-based integration)

• Basware provisions a customer-specific SFTP endpoint as part of service delivery
• SSH-encrypted, authenticated via username/password or certificate
• IP whitelisting required
• Inbound folder (customer pushes data) + Outbound folder (customer pulls data)
• XML files processed on a schedule maintained in Basware AP Automation Admin
• Supports: invoice transfer to accounting, master data import, user data import, PO import
• SFTP is separately quoted — not self-service

Webhooks (Push Notifications)

• Basware supports outbound webhooks via the Subscriptions API
• Subscribe to events, receive JSON notifications at your endpoint
• HMAC-SHA256 signature validation (x-bwapi-signature-256 header)
• No retry on failed delivery — use Tasks API to check for missed notifications
• Connection test via taskType: ConnectionTest on subscription creation

XML Integration

• Can run side-by-side with API — mix per interface or per company
• XML preferred for batch master data, service orders (XML-only), historical migrations
• Delivered over SFTP

SmartPDF

• Upload PDF invoices for OCR processing via POST /v1/smartpdf/invoiceUpload
• Returns pre-signed URL for file upload
• EU region only, API Key auth

Postman Collections

• Basware provides preconfigured Postman collections with example requests
• Available on developer portal for both AP Automation and P2P APIs
• Good for prototyping and testing

6. Orcha-Specific Deep Dive

For each core Orcha integration need, here is what Basware supports with exact endpoints, constraints, and confidence levels.

6.1 Write Reference Data (Cost Centers, Accounts, GL Codes)

Confidence: HIGH — Full CRUD confirmed with examples.

How it works:

• POST with externalCode → creates if new, full-updates if exists (clears omitted fields)
• PATCH with externalCode → partial update (preserves omitted fields)
• All support language translations and organizational inheritance
• Response: 200 OK on success, async processing in background

Constraints:

• Payment terms must be posted before vendors (validated during vendor import)
• externalCode must be unique and ≤ max field length
• Unchanged records are silently skipped (delta detection)
• DELETE removes from API only, not from Basware AP Automation target system
• Recommended: update entities one-by-one as they change (not bulk re-sync)

What the customer must configure:

• Company code matching their Basware AP Automation setup
• API credentials with write access to the relevant endpoints

6.2 Write Transactional Data (Invoices, Credit Notes)

Confidence: HIGH — Multiple confirmed paths for pushing invoices.

Network API invoice send flow:

1. Generate UUID for bumId and X-BW-REQUEST-ID
2. Upload attachments: POST /v2/files → get fileId
3. Send invoice JSON: POST /v2/invoices/{bumId} with processingPreference.sentTo (mandatory recipient endpoint)
4. Receive delivery notification via GET /v1.1/notifications?type=DocumentsReceived

SmartPDF flow:

1. POST /v1/smartpdf/invoiceUpload with receivingEmailAddress and notificationEmailAddress
2. Receive pre-signed URL in response
3. Upload PDF to pre-signed URL
4. Basware OCR processes the document

Constraints:

• Network API: recipient must be on Basware Network or reachable via supported e-invoicing standard
• SmartPDF: EU region only, API Key auth (not OAuth2)
• PO/goods receipt import: used for matching, not for creating invoices

6.3 Attach Documents (PDF/Image Attachments)

Confidence: HIGH — Confirmed via both Network Files API and Vault API.

Network Files upload flow:

1. POST /v2/files with multipart request (file + metadata: bumId, fileType)
2. Response: fileId
3. Reference fileId in the invoice JSON payload sent via Invoices API

Constraints:

• Files linked to a specific business document via bumId
• Binary upload or base64 encoding supported
• Basic Auth required

6.4 Trigger/Manage Approvals

Confidence: LOW — Basware does NOT expose approval actions via API. Approval workflows are internal to Basware AP Automation.

What this means for Orcha:

• Orcha can configure approval permissions via API (who can approve, at what levels)
• Orcha cannot programmatically trigger approve/reject actions on individual invoices
• Approval workflows must be managed within Basware's UI or admin module
• The API is designed as an ERP ↔ Basware bridge, not as a workflow automation tool

Workaround: Use webhooks to detect when an invoice exits the approval process (AccountingDocuments with taskSubType: WaitingForTransfer), then pull the approved invoice.

6.5 Read Status / Lifecycle Events

Confidence: HIGH — Two complementary mechanisms confirmed.

Status Query API (pull-based)

Returned statuses:

Webhooks (push-based)

Webhook payload:

[{
  "taskId": "string",
  "taskStatus": "New",
  "taskType": "AccountingDocuments",
  "taskSubtype": "WaitingForTransfer",
  "documentId": "string"
}]

Webhook security: HMAC-SHA256 signature in x-bwapi-signature-256 header. Format: t=TIMESTAMP,v1=SIGNATURE. Validate by computing HMAC-SHA256(key, "TIMESTAMP.NOTIFICATION_PAYLOAD").

Network API notifications (for e-invoicing):

Constraints:

• Webhooks: no retry on failed delivery — must use Tasks API as backup
• Status API: limited to 4 high-level statuses; use AccountingDocuments GET for detailed processing status
• Detailed processing statuses: WaitingForPrebook → PrebookInProgress → Prebooked → WaitingForTransfer → TransferInProgress → Transferred → Paid

6.6 Sync Reference Data Inbound (Read Accounts, Vendors, Cost Centers)

Confidence: MEDIUM — GET is supported on all master data endpoints, but with caveats.

Critical constraint: The AP Automation API is described as "one directional" — import APIs are for importing data from customer systems to Basware. The GET endpoints on master data return what was imported via API, not what exists natively in Basware AP Automation.

For reading Basware's actual production data (including data created within Basware), use the Data Access API instead:

• GET /v1/dataAccess/... endpoints provide raw production data
• Requires separate "Insights Essentials" or "Insights Pro" subscription
• Available in EU, US, AU regions

What this means for Orcha:

• If Orcha is the source of truth for reference data → push via API, read-back to verify ✓
• If Basware is the source of truth and Orcha needs to sync → need Data Access API (additional subscription)
• For most Orcha use cases (pushing invoice data + reference data TO Basware), the one-directional model works fine

7. Orcha Integration Capability Summary

8. Recommended Path Forward

Architecture

┌─────────────┐     HTTPS/JSON      ┌──────────────────────────┐
│             │ ──────────────────→ │  Basware AP Automation   │
│   Orcha     │     OAuth2 auth     │  API (api.basware.com)   │
│  (Clojure)  │ ←────────────────── │                          │
│             │     Webhooks        │  + Network API           │
│             │ ←────────────────── │  + SmartPDF API          │
└─────────────┘                     └──────────────────────────┘

Recommended Approach

Phased Integration Plan

Implementation Considerations

1. Authentication: OAuth2 client credentials flow → get token → include as Bearer token. Token refresh needed.
2. Async processing: POST returns 202 → poll RequestStatus or listen via webhooks
3. externalCode strategy: Use as primary key for upserts. Recommended format: orcha_{entity_type}_{id} (e.g., orcha_vendor_12345)
4. Delta detection: Basware silently skips unchanged records. Always include a modified timestamp or version field to force processing.
5. Rate limiting: Stay under 1000 calls/hour; ≥5 second gap between updates to same entity
6. Webhook reliability: No retry — implement polling fallback via Tasks API for missed notifications
7. Ordering constraints: Payment terms before vendors; accounts before invoices
8. Credentials: Must be obtained from Basware delivery consultant (not self-service)
9. Test environment: test-api.basware.com — develop and test before production

Access Requirements

• Prerequisite: Active Basware AP Automation or Supplier Management subscription
• API credentials: Obtained from Basware delivery consultant or technical partner manager
• Pricing: Not publicly listed; Basware platform starts ~$100K/year (API access included; Data Access API may be add-on)
• Gap: Approval management is NOT available via API — must remain in Basware UI

9. Sources

Official Documentation

• Basware Developer Portal
• AP Automation API Reference (Swagger)
• AP Automation API Manual
• Network APIs
• Network API Guide
• Network API Reference
• Data Access APIs
• Vault APIs Manual
• SmartPDF API Get Started
• Integration Selection Guide
• Get Started Guide
• FAQ
• Preconfigured Postman Templates

Swagger / OpenAPI

• EU Swagger
• US Swagger
• AU Swagger
• CA Swagger
• OAuth2 Swagger
• Push Notifications Swagger
• Network API v2 Reference

Basware Corporate

• Basware Integration Overview
• ERP Integrations
• Pricing
• Open APIs Blog Post
• Invoice Lifecycle Management
• Invoice Status Check Feature

iPaaS (no pre-built connectors found)

• Celigo Integration Marketplace
• Workato Connectors
• Make.com Integrations
• Zapier Apps
• Chift Unified APIs

Community

• Basware GitHub (SSO-gated)