# Authentication, input and response
## Rental Reference API
`POST` `https://api.altum.ai/rental-reference`
Post the address and optional parameters
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------- |
| x-api-key\* | String | Unique API Key from Altum. Create one via Mopsus () |
| Content-Type | String | application/json |
#### Request Body
| Name | Type | Description |
| --------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| postcode\* | String | 1234AB |
| housenumber\* | Number | 1 |
| houseaddition | String | A |
| innersurfacearea | Number | Any number greater than zero |
| furnished\_target | Boolean | 1 if the target is furnished |
| garden\_target | Boolean | 1 if the target has garden |
| reference\_number | Number | From 10 till 30 |
| date\_limit | Number | Between 6 and 60 in months search history of transactions |
| window\_limit | Boolean | 1 if you want to get the references only from the target's window |
| furnished | Boolean | 1 if you want the references to have the same furnished with the target (if exists) |
| garden | Boolean | 1 if you want the references to have the same value for garden (has garden or not) with the target (if exists) |
| weight\_innersurfacearea | Float | Takes values between 0 and 1. The weight to the inner surface area for displaying the final references. Default 0.8. |
| weight\_recency | Float | Takes values between 0 and 1. The weight to the recency for displaying the final references. Default 0.5. |
| weight\_distance | Float | Takes values between 0 and 1. The weight to the distance for displaying the final references. Default 0.8. |
{% tabs %}
{% tab title="200: OK Successful response" %}
```
{
"postcode": "1057AA",
"housenumber": "8",
"houseaddition": "2",
"longitude": "4.850520945759514",
"latitude": "52.36553700367924",
"street": null,
"city": null,
"inner_surface_area": "110",
"furnished": "1",
"garden": "1",
"reference_data": {
"market_rent": "1375",
"number_of_references": "366",
"rent_distribution": [
{
"min_sqm": "0",
"max_sqm": "35",
"sample_count": "2",
"rent_total": "1200",
"innersurfacearea_total": "67",
"rent_innersurfacearea": "17.9",
"avg_rent": "600"
},
{
"min_sqm": "35",
"max_sqm": "45",
"sample_count": "6",
"rent_total": "5091",
"innersurfacearea_total": "243",
"rent_innersurfacearea": "21.0",
"avg_rent": "848"
},
{
"min_sqm": "45",
"max_sqm": "55",
"sample_count": "12",
"rent_total": "14318",
"innersurfacearea_total": "612",
"rent_innersurfacearea": "23.4",
"avg_rent": "1193"
},
{
"min_sqm": "55",
"max_sqm": "65",
"sample_count": "18",
"rent_total": "21465",
"innersurfacearea_total": "1119",
"rent_innersurfacearea": "19.2",
"avg_rent": "1192"
},
{
"min_sqm": "65",
"max_sqm": "75",
"sample_count": "27",
"rent_total": "40233",
"innersurfacearea_total": "1936",
"rent_innersurfacearea": "20.8",
"avg_rent": "1490"
},
{
"min_sqm": "75",
"max_sqm": "85",
"sample_count": "30",
"rent_total": "41279",
"innersurfacearea_total": "2417",
"rent_innersurfacearea": "17.1",
"avg_rent": "1376"
},
{
"min_sqm": "85",
"max_sqm": "95",
"sample_count": "47",
"rent_total": "78329",
"innersurfacearea_total": "4219",
"rent_innersurfacearea": "18.6",
"avg_rent": "1667"
},
{
"min_sqm": "95",
"max_sqm": "105",
"sample_count": "35",
"rent_total": "55244",
"innersurfacearea_total": "3510",
"rent_innersurfacearea": "15.7",
"avg_rent": "1578"
},
{
"min_sqm": "105",
"max_sqm": "115",
"sample_count": "32",
"rent_total": "44343",
"innersurfacearea_total": "3558",
"rent_innersurfacearea": "12.5",
"avg_rent": "1386"
},
{
"min_sqm": "115",
"max_sqm": "125",
"sample_count": "41",
"rent_total": "67110",
"innersurfacearea_total": "4914",
"rent_innersurfacearea": "13.7",
"avg_rent": "1637"
},
{
"min_sqm": "125",
"max_sqm": "200",
"sample_count": "105",
"rent_total": "212150",
"innersurfacearea_total": "15252",
"rent_innersurfacearea": "13.9",
"avg_rent": "2020"
},
{
"min_sqm": "200",
"max_sqm": "inf",
"sample_count": "11",
"rent_total": "35750",
"innersurfacearea_total": "2648",
"rent_innersurfacearea": "13.5",
"avg_rent": "3250"
}
],
"reference_houses": [
{
"postcode": "1062JN",
"housenumber": "149",
"houseaddition": "L",
"street": "Postjesweg",
"city": "Amsterdam",
"housetype": "appartement",
"buildyear": "2024.0",
"innersurfacearea": "47",
"price_per_sqm2": "22.34",
"energylabel": "A+++",
"rental_price": "1050",
"rental_price_indexed": "1050",
"bedrooms": "1",
"furnishment": null,
"garden": "0",
"collection_date": "2024-01",
"distance": "653",
"weight": "1.0"
},
{
"postcode": "1072LJ",
"housenumber": "16",
"houseaddition": "B",
"street": "Ferdinand Bolstraat",
"city": "Amsterdam",
"housetype": "appartement",
"buildyear": "1875.0",
"innersurfacearea": "93",
"price_per_sqm2": "37.63",
"energylabel": "C",
"rental_price": "3500",
"rental_price_indexed": "3500",
"bedrooms": "2",
"furnishment": "0.0",
"garden": "0",
"collection_date": "2024-01",
"distance": "2873",
"weight": "0.989"
},
{
"postcode": "1072VC",
"housenumber": "136",
"houseaddition": "H",
"street": "Eerste Jan van der Heijdenstraat",
"city": "Amsterdam",
"housetype": "benedenwoning",
"buildyear": "1891.0",
"innersurfacearea": "71",
"price_per_sqm2": "31.69",
"energylabel": "C",
"rental_price": "2250",
"rental_price_indexed": "2250",
"bedrooms": "1",
"furnishment": "0.0",
"garden": "0",
"collection_date": "2024-05",
"distance": "3175",
"weight": "0.988"
},
{
"postcode": "1013MZ",
"housenumber": "70",
"houseaddition": "3",
"street": "Houtmankade",
"city": "Amsterdam",
"housetype": "appartement",
"buildyear": "1926.0",
"innersurfacearea": "55",
"price_per_sqm2": "32.73",
"energylabel": "A",
"rental_price": "1800",
"rental_price_indexed": "1800",
"bedrooms": "1",
"furnishment": null,
"garden": "0",
"collection_date": "2024-03",
"distance": "3250",
"weight": "0.987"
},
{
"postcode": "1066LC",
"housenumber": "57",
"houseaddition": null,
"street": "Kinrooistraat",
"city": "Amsterdam",
"housetype": "tussenwoning",
"buildyear": "1992.0",
"innersurfacearea": "91",
"price_per_sqm2": "21.98",
"energylabel": "B",
"rental_price": "2000",
"rental_price_indexed": "2000",
"bedrooms": "2",
"furnishment": "0.0",
"garden": "0",
"collection_date": "2024-01",
"distance": "3238",
"weight": "0.987"
},
{
"postcode": "1081GT",
"housenumber": "17",
"houseaddition": null,
"street": "Cannenburg",
"city": "Amsterdam",
"housetype": "tussenwoning",
"buildyear": "1965.0",
"innersurfacearea": "212",
"price_per_sqm2": "35.38",
"energylabel": "A",
"rental_price": "7500",
"rental_price_indexed": "7500",
"bedrooms": "4",
"furnishment": "0.0",
"garden": "0",
"collection_date": "2024-01",
"distance": "4031",
"weight": "0.981"
},
{
"postcode": "1081BL",
"housenumber": "23",
"houseaddition": null,
"street": "Soetendaal",
"city": "Amsterdam",
"housetype": "geschakelde woning",
"buildyear": "1962.0",
"innersurfacearea": "171",
"price_per_sqm2": "23.39",
"energylabel": "D",
"rental_price": "4000",
"rental_price_indexed": "4000",
"bedrooms": "5",
"furnishment": null,
"garden": "0",
"collection_date": "2023-12",
"distance": "4425",
"weight": "0.979"
},
{
"postcode": "1082EG",
"housenumber": "243",
"houseaddition": "2",
"street": "Kastelenstraat",
"city": "Amsterdam",
"housetype": "appartement",
"buildyear": "1960.0",
"innersurfacearea": "75",
"price_per_sqm2": "26.67",
"energylabel": "F",
"rental_price": "2000",
"rental_price_indexed": "2000",
"bedrooms": "2",
"furnishment": "1.0",
"garden": "0",
"collection_date": "2023-12",
"distance": "4663",
"weight": "0.978"
},
{
"postcode": "1032LB",
"housenumber": "52",
"houseaddition": null,
"street": "Hulstweg",
"city": "Amsterdam",
"housetype": "appartement",
"buildyear": "2024.0",
"innersurfacearea": "68",
"price_per_sqm2": "20.96",
"energylabel": "Niet beschikbaar",
"rental_price": "1425",
"rental_price_indexed": "1425",
"bedrooms": "2",
"furnishment": null,
"garden": "0",
"collection_date": "2024-01",
"distance": "5276",
"weight": "0.975"
},
{
"postcode": "1032LB",
"housenumber": "68",
"houseaddition": null,
"street": "Hulstweg",
"city": "Amsterdam",
"housetype": "appartement",
"buildyear": "2024.0",
"innersurfacearea": "51",
"price_per_sqm2": "23.73",
"energylabel": "Niet beschikbaar",
"rental_price": "1210",
"rental_price_indexed": "1210",
"bedrooms": "1",
"furnishment": null,
"garden": "0",
"collection_date": "2024-01",
"distance": "5276",
"weight": "0.975"
}
]
}
}
```
{% endtab %}
{% tab title="422: Unprocessable Entity Wrong input format" %}
```
{
"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="400: Bad Request Unsuccessful response" %}
```json
{
'Output': 'The given house address not found in database, the combination of Post Code, House Number and House Addition does not exist.'
}
```
{% endtab %}
{% tab title="400: Bad Request Unsuccessful response" %}
```
{
'Output': 'The garden of the given house is unknown. Please fill the garden_target input.'
}
```
{% endtab %}
{% tab title="400: Bad Request Unsuccessful response" %}
```
{
'Output': 'The furnishment type of the given house is unknown. Please fill the furnished_target input.'
}
```
{% 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 %}
{% tab title="500: Internal Server Error Service is not available and/or down" %}
```
{
"message": "Internal server error"
}
```
{% endtab %}
{% endtabs %}
## Request body
#### Example request
```
{
"postcode": "1057AA",
"housenumber": 8,
"houseaddition": "2",
"innersurfacearea": 110,
"furnished_target": 1,
"garden_target": 1,
"reference_number": 10,
"date_limit": 6,
"window_limit": 0,
"furnished": 0,
"garden": 0,
"weight_innersurfacearea": 0.3,
"weight_recency": 0.9,
"weight_distance": 0.1
}
```