Aarven API

A simple REST API for creating bookings and reading your chart of accounts and company data — built for automation platforms like Zapier and Make, and for custom scripts.

Base URL

All endpoints are served under:

https://aarven.ch/api/v1

Authentication

Create an API key under Settings > API Access in your Aarven account. Each key is tied to exactly one company and has one or more scopes (see below). The plaintext key is shown only once, right after creation — store it securely.

Send it as a Bearer token on every request:

Authorization: Bearer <api-key>

Scopes

• BookingsWrite — required for POST /bookings
• AccountsRead — required for GET /accounts and GET /tax-codes
• CompanyRead — required for GET /company

Rate limits

60 requests per minute per API key. Exceeding the limit returns 429 Too Many Requests.

Errors

Errors are returned as JSON with a single error field, alongside a non-2xx HTTP status code:

{ "error": "The 'Idempotency-Key' header is required." }

Endpoints

GET /company

Returns the company the API key belongs to.

curl https://aarven.ch/api/v1/company \
  -H "Authorization: Bearer <api-key>"

{
  "id": "20000000-0000-0000-0000-000000000001",
  "name": "Muster GmbH",
  "currency": "CHF"
}

GET /accounts

Returns the active chart of accounts for the company.

curl https://aarven.ch/api/v1/accounts \
  -H "Authorization: Bearer <api-key>"

[
  {
    "id": "edbd6280-8950-43e1-b77a-cac276455e1f",
    "accountNumber": "1020",
    "name": "Bank",
    "accountType": "Asset",
    "currency": "CHF"
  }
]

GET /tax-codes

Returns the active tax codes (VAT rates) for the company — used as the taxCodeId on booking lines.

curl https://aarven.ch/api/v1/tax-codes \
  -H "Authorization: Bearer <api-key>"

[
  {
    "id": "3f1a2b4c-1111-2222-3333-444455556666",
    "code": "V81",
    "name": "Normalsatz 8.1%",
    "rate": 0.081,
    "taxType": "OutputTax"
  }
]

POST /bookings

Creates a booking (a balanced set of debit/credit lines). Requires a Idempotency-Key header — an arbitrary unique string of your choosing. Retrying the same request with the same key returns the original booking instead of creating a duplicate.

curl https://aarven.ch/api/v1/bookings \
  -H "Authorization: Bearer <api-key>" \
  -H "Idempotency-Key: <unique-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingDate": "2026-08-28",
    "description": "Payment received",
    "reference": "INV-1042",
    "autoPost": true,
    "lines": [
      { "accountId": "edbd6280-8950-43e1-b77a-cac276455e1f", "direction": "Debit",  "amount": 120.00 },
      { "accountId": "9eb9c0e7-8a71-452b-a543-e5d8390648d8", "direction": "Credit", "amount": 120.00 }
    ]
  }'

Fields:

• bookingDate (required) — YYYY-MM-DD
• description (required)
• reference (optional) — e.g. an invoice or receipt number
• autoPost (optional, default true) — when false, the booking is saved as a draft
• lines (required) — at least one line; the sum of all Debit amounts must equal the sum of all Credit amounts
  • accountId (required) — see GET /accounts
  • direction (required) — "Debit" or "Credit"
  • amount (required)
  • description, paymentReference (both optional)
  • taxCodeId (optional) — see GET /tax-codes; omit for no VAT on that line
  • amountType (optional, default "Gross") — "Gross" (VAT-inclusive) or "Net" (VAT-exclusive); only relevant together with taxCodeId
  • foreignAmount (optional)

Response (201 Created):

{ "id": "bd70f098-18ef-43ab-bf7d-22e5f21cbaa5" }

VAT example

Setting taxCodeId on a line automatically adds a separate VAT line for you — you never need to compute or add the tax amount yourself. Here, 20.96 booked against "Raumkosten" with an 2.6% tax code creates that line plus a second, auto-generated 0.54 VAT line, both balanced against a single 21.50 payment-account line:

curl https://aarven.ch/api/v1/bookings \
  -H "Authorization: Bearer <api-key>" \
  -H "Idempotency-Key: <unique-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "bookingDate": "2026-08-28",
    "description": "Office rent",
    "autoPost": true,
    "lines": [
      { "accountId": "<cash-account-id>",  "direction": "Debit",  "amount": 21.50 },
      {
        "accountId": "<expense-account-id>",
        "direction": "Credit",
        "amount": 21.50,
        "taxCodeId": "<tax-code-id>",
        "amountType": "Gross"
      }
    ]
  }'

Questions

Reach out at [email protected] if you run into anything unclear or want help wiring up an integration.