# Authentication, input and response

## Determine the estimated current or potential NTA 8800 energy label

<mark style="color:green;">`POST`</mark> `https://api.altum.ai/v2/energylabel/apartments`

#### Headers

| Name                                        | Type   | Description                                                                 |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------- |
| x-api-key<mark style="color:red;">\*</mark> | string | Unique API Key from Altum. Create one via Mopsus(<https://mopsus.altum.ai>) |
| Content-Type                                | string | application/json                                                            |

#### Request Body

<table><thead><tr><th>Field</th><th>Type</th><th width="187">Description</th><th>Example/Default</th></tr></thead><tbody><tr><td>postcode<mark style="color:red;">*</mark></td><td>string</td><td>zip code in six-character format</td><td>1234AB</td></tr><tr><td>housenumber<mark style="color:red;">*</mark></td><td>integer</td><td>house number</td><td>1</td></tr><tr><td>houseaddition</td><td>string</td><td>addition to the house number</td><td>A</td></tr><tr><td>position</td><td>integer</td><td><code>1</code> = 'Corner ground floor'
<br><code>2</code> = 'In between ground floor'
<br><code>3</code> = 'Corner mid floor'
<br><code>4</code> = 'In between mid floor'
<br><code>5</code> = 'Corner top floor'
<br><code>6</code> = 'In between top floor'
<br><code>7</code> = 'Entire top floor'</td><td>Default: 1</td></tr><tr><td>floors</td><td>integer</td><td><p>Does the unit has one or more floors?</p><p>1 = 'Single'</p><p>2 = 'Multiple'</p></td><td>Default: 1</td></tr><tr><td>back_facade</td><td>boolean</td><td><p>Does the unit has as back facade?</p><p>false = no</p><p>true = yes</p></td><td>Default: false</td></tr><tr><td>build_year</td><td>integer</td><td>build year</td><td>1960</td></tr><tr><td>apartment_type</td><td>integer</td><td><code>1</code> = 'Galerijflat'
<br><code>2</code> = 'Portiekflat'
<br><code>3</code> = 'Maisonnette'
<br><code>4</code> = 'Benedenwoning'
<br><code>5</code> = 'Bovenwoning'
<br><code>6</code> = 'Portiekwoning'
</td><td>2</td></tr><tr><td>inner_surface_area</td><td>float</td><td>inner surface area (m2)</td><td>70</td></tr><tr><td>wall_insulation</td><td>integer</td><td>see <a href="/pages/DTplmmMlP75yYyVJdcVZ">Measures</a></td><td>2</td></tr><tr><td>floor_insulation</td><td>integer</td><td>see <a href="/pages/DTplmmMlP75yYyVJdcVZ">Measures</a></td><td>2</td></tr><tr><td>roof_insulation</td><td>integer</td><td>see <a href="/pages/DTplmmMlP75yYyVJdcVZ">Measures</a></td><td>2</td></tr><tr><td>living_room_windows</td><td>integer</td><td>see <a href="/pages/DTplmmMlP75yYyVJdcVZ">Measures</a></td><td>2</td></tr><tr><td>installation</td><td>integer</td><td>see <a href="/pages/DTplmmMlP75yYyVJdcVZ">Measures</a></td><td>Default: 4</td></tr><tr><td>shower</td><td>integer</td><td>see <a href="/pages/DTplmmMlP75yYyVJdcVZ">Measures</a></td><td>Default: 1</td></tr><tr><td>cooling</td><td>integer</td><td><p>Is there a cooling system present?</p><p><code>1</code> = No cooling</p><p><code>2</code> = Air conditioning unit, direct air cooling</p></td><td>Default: 1</td></tr><tr><td>ventilation</td><td>integer</td><td>see <a href="/pages/DTplmmMlP75yYyVJdcVZ">Measures</a></td><td>1</td></tr><tr><td>electric_cooking</td><td>integer</td><td><p>What is used for cooking?</p><p><code>1</code> = Gas stove</p><p><code>2</code> = Electric stove</p></td><td><p>Default: 2 if Installation in [6,7],</p><p>Else 1</p></td></tr><tr><td>inhabitants</td><td>integer</td><td>number of people living in the house</td><td>Default: 3</td></tr><tr><td>solar_panels</td><td>list</td><td>see <a href="/pages/DTplmmMlP75yYyVJdcVZ">Measures</a></td><td></td></tr><tr><td>number_of_solar_panels</td><td>integer</td><td>see <a href="/pages/DTplmmMlP75yYyVJdcVZ">Measures</a></td><td></td></tr></tbody></table>

{% hint style="info" %}
*<mark style="color:red;">**Specifying both the position and the floors of the apartment is recommended for optimal results.**</mark>*
{% endhint %}

## Differences from Houses endpoint

* apartment\_type instead of house\_type
* roof\_insulation instead of sloped\_roof\_insulation and flat\_roof\_insulation
* no berdroom\_windows
* apartment\_type is not important but position and floors are

## Request body

```
{
  "postcode": "3024XL",
  "housenumber":227,
  "houseaddition": "B",
  "position": 3,
  "floors": 1
}
```

## Response Status Codes

{% tabs %}
{% tab title="200: OK Successful response" %}

```
{
  "Output": {
    "warnings": [],
    "tip": null,
    "postcode": "3024XL",
    "housenumber": 227,
    "houseaddition": "B",
    "build_year": 1927,
    "inner_surface_area": 74,
    "apartment_type": "Portiekwoning",
    "installation": 4,
    "wall_insulation": 1,
    "roof_insulation": null,
    "floor_insulation": null,
    "living_room_windows": 2,
    "shower": 1,
    "ventilation": 1,
    "cooling": 1,
    "electric_cooking": 1,
    "solar_panels": null,
    "CO2": 2208,
    "definitive_energy_label": null,
    "definitive_energy_label_type": null,
    "definitive_energy_label_validity_date": null,
    "definitive_BENG2_score": null,
    "current_estimated_energy_label": "C",
    "current_estimated_BENG2_score": 221,
    "estimated_gas_usage": 805,
    "estimated_energy_usage": 2262,
    "estimated_city_heating_usage": 0,
    "solar_panel_yield": 0,
    "measures_method": 2,
    "accuracy_indicator": 3,
    "response_meta": null
  }
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity" %}

```
{
  "detail": [
    {
      "loc": [
        "body",
        "postcode"
      ],
      "msg": "string does not match regex \"^(?!1000|1001|1002|1003|1004|1005|1006|1007|1008|1009|1010)[1-9][0-9]{3}[A-Z]{2}$\"",
      "type": "value_error.str.regex",
      "ctx": {
        "pattern": "^(?!1000|1001|1002|1003|1004|1005|1006|1007|1008|1009|1010)[1-9][0-9]{3}[A-Z]{2}$"
      }
    }
  ]
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```
{ 
    "detail": "Address not found in database, combination of zip code   and house number." 
}
```

```
{
     "detail": "No measures suggested for this combination of input."
}
```

```
{
     "detail": "Code used in exclude_measure parameter is invalid"
}
```

```
{
     "detail": "No housing variant with the selected installation options found with which the goal can be reached within the investment limit. Try again with different inputs and/or different search criteria."
}
```

```
{
     "detail": "Gevelisolatie code ongeldig"
}
```

{% endtab %}

{% tab title="301: Moved Permanently" %}

```
{ 
    "detail": "Unable to check house."
}
```

{% endtab %}

{% tab title="303: See Other House-type error" %}

```
{ 
    "detail": "The house type of the given house was not found in database. Use house_type parameter instead."
}
```

{% endtab %}

{% tab title="500: Internal Server Error" %}

```
{
	"message": "Internal server error"
}
```

{% endtab %}

{% tab title="401: Unauthorized No access" %}

```
{
    'Output': 'Please use https://api.altum.ai or visit https://mopsus.altum.ai to make your request.'
}
```

{% endtab %}

{% tab title="403: Forbidden Forbidden" %}

```
{
	"message": "Missing Authentication Token"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.altum.ai/english/sustainability/nta-8800-energylabel-v2-api/apartments/authentication-input-and-response.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.