API Reference
Tax Matrix
Returns a RoadTax and YearlyTax matrix for a single vehicle across every combination of entity profile and Belgian region, in one call. Built for partners who need a full tax overview for a vehicle without issuing one request per profile/region combination.
GET /GetTaxMatrix
Requires calculation access
This endpoint needs calculation access enabled on your subscription, in addition to a valid key. See Authentication.
Request
GET https://api.ototo.be/v1/GetTaxMatrix?id={carDetailId}&subscription-key=YOUR_KEY
Query parameters
| Parameter | Type | Required | Description |
|---|
id | guid | required | The car detail's unique identifier — see Car Details |
Response
200 OK
Response shape (abridged — real responses include every profile × region combination)
{
"carDetailId": "12345678-1234-1234-1234-123456789abc",
"rows": [
{
"status": "Private",
"registrationOn": "PrivateRegistration",
"regions": [
{ "region": "Brussels", "roadTax": 662.64, "yearlyTax": 1320.00 },
{ "region": "Flanders", "roadTax": 336.62, "yearlyTax": 980.00 },
{ "region": "Wallonia", "roadTax": 662.64, "yearlyTax": 1100.00 }
]
},
{
"status": "SoleProprietor",
"registrationOn": "CompanyRegistration",
"regions": [
{ "region": "Brussels", "roadTax": 662.64, "yearlyTax": 1320.00 },
{ "region": "Flanders", "roadTax": 336.62, "yearlyTax": 980.00 },
{ "region": "Wallonia", "roadTax": 662.64, "yearlyTax": 1100.00 }
]
}
]
}
| Field | Type | Description |
|---|
carDetailId | guid | The car detail ID that was requested |
rows | array | One entry per entity/profile combination — see below |
Each entry in rows
| Field | Type | Description |
|---|
status | enum | Taxpayer status — see ProfileStatus on the Calculate page |
registrationOn | enum | Who the vehicle is registered to — see RegistrationOn on the Calculate page |
regions | array | Tax values, one entry per region — see below |
Each entry in regions
| Field | Type | Description |
|---|
region | enum | Belgian region — see Region on the Calculate page |
roadTax | decimal? | Registration tax (BIV / TMC), excl. VAT. null if there's no result (e.g. an exemption applies). |
yearlyTax | decimal? | Annual road tax (verkeersbelasting), excl. VAT. null if there's no result. |
Built to extend without a schema change
The response is a plain collection with no fixed property per region or entity type. A new value added to Region appears as an extra entry inside regions on every row; a new ProfileStatus or RegistrationOn value appears as an extra row. Iterate over rows and regions dynamically — don't rely on array position or a hardcoded set of property names, since the matrix can grow over time.
Error responses
| Status | Condition |
|---|
400 | id is missing or not a valid GUID |
401 | Subscription key is missing or invalid, the subscription is inactive, or calculation access isn't enabled — see Authentication |
404 | No car detail found for the given id |
Tax Matrix vs. Calculate
| Calculate | Tax Matrix |
|---|
| Input | Vehicle object or a stored car detail ID | Car detail ID only |
| Profile | You specify one profile | Every profile computed automatically |
| Regions | You specify one region | Every region computed automatically |
| Calculators | Any combination via viewOptions | RoadTax and YearlyTax only |
| Best for | A detailed single-scenario calculation | A full tax overview for a dashboard or comparison view |
See also
- Calculate — detailed single-profile calculation, including benefit-in-kind, fiscal deduction, and CO₂ contribution
- Car Details — create the vehicle you reference by
id