# Authentication, input and response

## Request housing features for Dutch residential properties

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

#### 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

| Name                                          | Type   | Description                                                                  |
| --------------------------------------------- | ------ | ---------------------------------------------------------------------------- |
| postcode<mark style="color:red;">\*</mark>    | string | Zipcode of the object                                                        |
| valuationdate                                 | string | Enter as YYYYMMDD, gives newest transaction till that date. Default is TODAY |
| houseaddition                                 | string | House letter and addition of the object                                      |
| housenumber<mark style="color:red;">\*</mark> | number | House number of the object                                                   |

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

```
{
	"Output": {
		"bag_id": "0363010000710354",
		"postcode": "1011EW",
		"housenumber": "48",
		"houseaddition": "None",
		"valuation_date": "20240104",
		"city": "Amsterdam",
		"street": "Koningsstraat",
		"house_type_generic": "Tussen/rijwoning",
		"house_type_specific": "None",
		"type_house_construction": "Herenhuis, tussenwoning",
		"building_status": "Pand in gebruik",
		"inner_surface_area": "216.0",
		"outer_surface_area": "76.0",
		"build_year": "1906.0",
		"volume": "548.0",
		"rooms": "8.0",
		"number_of_bathrooms": "3.0",
		"garden_orientation": "None",
		"garden_size": "None",
		"garden_location": "Achtertuin",
		"monument": "0",
		"monument_description": "Geen monument / Onbekend",
		"longitude": "4.902011945627775",
		"latitude": "52.37216745876808",
		"neighbourhood_code": "BU03630404",
		"neighbourhood_name": "Nieuwmarkt",
		"municipality_code": "363.0",
		"municipality_name": "Amsterdam",
		"province": "Noord-Holland",
		"use_ownership": "V",
		"rent_ownership": "E",
		"rent_ownership_class": "4.5",
		"ozb_tax": "0.0431",
		"waste_tax_one_person": "22.72",
		"waste_tax_more_persons": "330.34",
		"sewage_tax_one_person": "440.18",
		"sewage_tax_more_persons": "160.43",
		"protected_cityviews": "2",
		"protected_cityview_names": "['Amsterdam - Binnen de Singelgracht', 'Amsterdam - Nieuwmarktbuurt']"
	}
}
```

{% endtab %}

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

```
{
  "Output": "The given house address not found in database, the combination of Post Code, House Number and House Addition does not exist."
}

{
  "Output": "We are not able to provide data at the moment."
}
```

{% endtab %}

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

```
{
	"detail": [
		{
			"loc": [
				"body",
				43
			],
			"msg": "Expecting value: line 3 column 18 (char 43)",
			"type": "value_error.jsondecode",
			"ctx": {
				"msg": "Expecting value",
				"doc": "{\n  \"postcode\": \"2201PZ\",\n  \"housenumber\": a,\n  \"valuationdate\": \"20121001\"\n}",
				"pos": 43,
				"lineno": 3,
				"colno": 18
			}
		}
	]
}
```

{% endtab %}

{% tab title="500: Internal Server Error Service is not available and/or down" %}

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

{% endtab %}

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

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

{% 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 %}
{% endtabs %}

## Request body

#### Example request

```
{
  "postcode": "2201PZ",
  "housenumber": 11,
  "valuationdate": "20221001"
}
```