FAQ

Frequently asked questions about API access, requests, data queries and custom fields.

Calling the API

What is my API base URL?

https://{subdomain}.vario.cloud/api/vario

{subdomain} is your own tenant subdomain — the one you use to reach your installation.

The server address shown at the top of the interactive API Reference is an internal placeholder and is not reachable from outside. Don't copy it.

For the exact URL and the endpoints enabled for your installation, download the tenant-specific OpenAPI specification from your ERP in support mode — the servers entry holds the authoritative value.

→ REST API Introduction

Every request fails with 403 Forbidden, even with a valid token. Why?

You are almost certainly missing a User-Agent header. The API rejects requests without one.

This is not arbitrary: the platform uses User-Agent to identify the calling app, which is what makes webhook suppression work. The App Framework sends your appIdentifier as the value.

What is the difference between the SSO URL and the API URL?

They are two different hosts and it is the single most common mix-up:

Purpose	URL
Getting and refreshing tokens	https://sso.vario.cloud/realms/<TENANT>/protocol/openid-connect/token
Making API calls	https://{subdomain}.vario.cloud/api/vario

→ REST API Authentication

I'm getting 429 Too Many Requests.

You exceeded the rate limit of 40 requests per 6 seconds. Pause and retry with a delay; continuing to burst keeps you throttled.

→ Rate limiting

What do 402, 403 and 422 mean?

Status	Meaning
402	A license is missing or its limit is exceeded — at runtime
403	A permission is missing, or your request had no User-Agent
422	Validation failed — including a missing required license at install time

Reading and writing data

How do I find the right field path for a query?

Don't look it up in documentation — enumerate it. The available groups, templates and field paths depend on your installation and change between versions, and a path copied from a document may not exist in your version.

→ Don't guess field paths — ask the API

The same principle applies to navigating to a related entity: there is a dedicated call that returns all entities with their relations, which is how you discover joins.

What is the difference between account.number, customer.number and accountingNumber?

An account is the address. Numbers then exist per business relationship — an account can be a customer, a supplier and a sales agent at the same time, each with its own numbers.

Path	Meaning
account.number	Address number — identifies the account itself
customer.number	Customer number, valid in the customer relationship
customer.accountingNumber	The bookkeeping (FiBu) customer number
customer.ourNumber	Your supplier number, as the customer knows you
supplier.number	Supplier number, valid in the supplier relationship
supplier.accountingNumber	The bookkeeping (FiBu) supplier number
supplier.ourNumber	Your customer number, as the supplier knows you

The pattern is symmetric, so you can reason about any of them:

• number — the partner's number in that relationship,
• accountingNumber — its counterpart for financial accounting,
• ourNumber — the number the partner uses for you.

For accounting exports this matters: the export uses the relationship's accountingNumber and falls back to number when it is empty. Writing an identifier into the wrong one silently changes which account a booking lands on.

My paged query returns duplicates and misses rows.

You are paging over an unsorted result set. Offset paging is undefined without an order: pages overlap, some rows arrive twice and others never arrive — differently on each run. The backend adds no default order.

Always sort by a unique column (id is the safe choice), and deduplicate afterwards as a safety net.

Why is moreElements never true?

Because it is a string. Pagination information arrives in response headers and is exposed as strings — compare with === 'true', not as a boolean.

→ VQL

How do I store my own data on ERP records?

With Custom Fields. Attach them to articles, accounts, documents, listings and more, then query them by path:

SELECT id, custom.myapp.externalId
  FROM article.query
 WHERE custom.myapp.externalId NOTNULL

This is the standard way to store external reference IDs and sync state.

How do I get IntelliSense for the API and for scripting?

Install the @vario-software/types package — it provides type definitions for the platform, including the API schemas and the scripting interfaces.