Skip to content

API Reference

The xTool REST API is used for integration: creating and managing documents, validating and converting formats, listing transactions, and more. The base URL is provided with your environment (e.g. by your administrator). See Setup and API keys and permissions.

Modern API Reference (Scalar) Traditional Swagger

The interactive documentation (Scalar or Swagger) lets you browse all endpoints, send test requests, and view request/response schemas. Below is a short onboarding: API versioning, authentication, and general conventions.

Versioning

  • v1 — Supported. See Migration for moving to v2.
  • v2 — Current. Use v2 for all new work. Endpoints are under /api/v2/.

Authentication

Send your API key in every request. The key is tied to an organisation and a set of allowed API methods. Common way to send the key:

  • Header: x-api-key: YOUR_API_KEY

Active organisation (X-Active-Org-Id). Optional header with the organisation UUID. It defines which organisation context the request runs in: documents, transactions, organisation list, etc. are scoped to the active organisation. If the header is omitted, the active organisation is the one the API key belongs to. If present, that organisation is used as active; it must be the key's organisation or a descendant in the hierarchy (one key for a parent org can act on behalf of a child org). Format: X-Active-Org-Id: <organisation_uuid>.

Use the method required by your deployment. See API keys and permissions.

Conventions

  • Request/response — Most endpoints use JSON. Document content can be XML or PDF (e.g. get XML, get PDF, upload XML).
  • Status codes — 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Validation Error, 500 Server Error.
  • Pagination — List endpoints support limit and offset.
  • Sorting — sort_by and sort_order where applicable.
  • Search — search query parameter where applicable.
  • IDs — Resources use UUID (e.g. document_id, organisation_id, transaction_id).

Error handling

On 4xx or 5xx responses, the body contains an error structure. Typically a detail field with a message. For 422 Validation Error, the response may include a list of validation errors (e.g. location and message). Use this to fix the request and retry.

Main API groups

Area Endpoints (examples) Version
Auth current context (organisation, user) v2
Documents list, get, get model, get xml, upload model/xml, update model/xml, send, delete v2
Format transform (model↔XML, model→PDF, XML→model, XML→PDF), validate (model, XML), detect XML, convert (model, XML) v2
Transactions list, get (with optional status_log) v2
Organisations list v2
Peppol Lookup check-existence, business-card, document-types, endpoints v2
PDF merge (multiple PDFs into one) v2
v1 documents, invoice convert, PDF — supported v1

See Migration for moving from v1 to v2.