OOtoto API Docs
API Reference

Calculate

Calculates taxation and other financial details for a vehicle against one driver profile. Accepts either an inline vehicle or a reference to a car detail already stored via Car Details.

POST /Calculate
Requires calculation access

This endpoint needs calculation access enabled on your subscription, in addition to a valid key. See Authentication.

Request

POST https://api.ototo.be/v1/Calculate?subscription-key=YOUR_KEY
Content-Type: application/json

Body

FieldTypeRequiredDescription
carDetailIdguidsee noteReference to a car detail already stored via Car Details
carDetailobjectsee noteInline vehicle object — same shape as the Car Details object
userProfileobjectrequiredProfile of the person the calculation is for
optionsobjectrequiredRegistration date, discounts, and other calculation options
versionstringoptionalClient version tag, currently "1"; stored for auditing only

Either carDetailId or carDetail must be provided. If both are given, carDetail takes precedence.

userProfile

FieldTypeRequiredDescription
postalCodeintrequiredBelgian postal code (1000–9992)
statusenumrequiredEntity type of the taxpayer — see ProfileStatus below
registrationOnenumrequiredWho the vehicle is registered to — see RegistrationOn below
regionRegistrationenumrequiredBelgian region used for regional taxes — see Region below
viewOptionsintoptionalBitmask of which calculators to run — see ViewOptions below
hasFuelCardbooloptionalWhether a fuel card is included
languagestringoptionalResult language: nl, fr, or en

options

FieldTypeRequiredDescription
registrationDatedaterequiredIntended registration date (yyyy-MM-dd)
orderDatedateoptionalOrder/acquisition date (yyyy-MM-dd), used for the fiscal deduction regime. Falls back to registrationDate if omitted.
totalDiscountdecimaloptionalTotal dealer discount, incl. VAT
ownMonthlyCostdecimaloptionalEmployee's own monthly contribution
Enum values

Enum fields accept either their numeric value or their name as a JSON string — "status": 30 and "status": "SelfEmployed" are both valid. Examples on this page use names for readability.

ProfileStatus

NameValueMeaning (NL)
Private10Particulier
SoleProprietor20Eenmanszaak
SelfEmployed30Bedrijf

RegistrationOn

NameValueMeaning (NL)
PrivateRegistration10Op naam particulier
CompanyRegistration20Op naam bedrijf
LeasingCompanyRegistration30Op naam leasingmaatschappij

Region

NameValueMeaning (NL)
Flanders0Vlaanderen
Wallonia1Wallonië
Brussels2Brussel

ViewOptions (bitmask)

FlagValueCalculator
RoadTax1BIV / TMC (registration tax)
YearlyTax2Verkeersbelasting (yearly road tax)
BenefitInKind4Voordeel alle aard (VAA)
FiscalDeduction8Fiscale aftrekbaarheid
RejectedExpenses16Verworpen uitgaven
CO2Contribution32CO₂-bijdrage

Combine flags with a bitwise OR — e.g. 63 runs every calculator; 37 (1 + 4 + 32) runs RoadTax, BenefitInKind, and CO2Contribution.

Response

200 OK

FieldTypeDescription
calculationIdguidID of the saved calculation request
linesarrayOne entry per calculator that ran — see below

Each entry in lines

FieldTypeDescription
namestringDisplay name of the calculation, localised
descriptionstringAdditional description, localised (may be null)
viewOptionenumWhich calculator produced this line — see ViewOptions above
valuestringFormatted display value, e.g. "662.64€"
rawValuedecimalNumeric value for programmatic use
yearintFiscal year the value applies to
urlstringLink to source legislation, when available (otherwise null)
hasUrlboolWhether url is set

A calculation typically returns one line per requested calculator for the current fiscal year, and a second for the following year where the tax recurs annually (yearly road tax, benefit in kind, etc.). One-off taxes like RoadTax appear once.

Error responses

StatusCondition
400The request body couldn't be parsed, userProfile or options is missing, postalCode is out of range, or the vehicle data is invalid
401Subscription key is missing or invalid, the subscription is inactive, or calculation access isn't enabled — see Authentication
404carDetailId was provided but no matching car detail exists

Example

Request — using a stored car detail 
POST https://api.ototo.be/v1/Calculate?subscription-key=YOUR_KEY
Content-Type: application/json

{
  "carDetailId": "12345678-1234-1234-1234-123456789abc",
  "userProfile": {
    "postalCode": 2000,
    "status": "SelfEmployed",
    "registrationOn": "LeasingCompanyRegistration",
    "regionRegistration": "Flanders",
    "viewOptions": 63
  },
  "options": {
    "registrationDate": "2026-06-01",
    "totalDiscount": 2420.00
  }
}
Request — using an inline vehicle 
POST https://api.ototo.be/v1/Calculate?subscription-key=YOUR_KEY
Content-Type: application/json

{
  "version": "1",
  "carDetail": {
    "firstRegistration": "2019-01-01",
    "catalogPrice": 135000.00,
    "fuel": "Electric",
    "euroStandard": "NA",
    "kilowatt": 286.00,
    "wltp": 64,
    "nedC2": 58
  },
  "userProfile": {
    "postalCode": 3440,
    "status": "SelfEmployed",
    "registrationOn": "CompanyRegistration",
    "regionRegistration": "Flanders",
    "viewOptions": 63,
    "language": "nl",
    "hasFuelCard": false
  },
  "options": {
    "registrationDate": "2026-06-01"
  }
}
Response — 200 OK (abridged) 
{
  "calculationId": "0c6022a3-5a2e-49fd-f68a-08d8e3c2315a",
  "lines": [
    {
      "name": "Voordeel alle aard",
      "description": "Per jaar (gebaseerd op NEDC2)",
      "viewOption": 4,
      "value": "17249.76€",
      "rawValue": 17249.76,
      "year": 2026,
      "url": null,
      "hasUrl": false
    },
    {
      "name": "Verkeersbelasting",
      "description": null,
      "viewOption": 2,
      "value": "55.24€",
      "rawValue": 55.24,
      "year": 2026,
      "url": null,
      "hasUrl": false
    }
  ]
}

See also

  • Tax Matrix — RoadTax & YearlyTax across every profile and region for a vehicle, in a single call
  • Car Details — create the vehicle you reference by carDetailId
  • Webhooks — get notified when calculation rules change so you know what to recalculate
← Car Details Tax Matrix →