# Authentication, input and response

## Interactive Reference API

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

Post the address and optional parameters

#### 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  | 1234AB                                                                                                                                                        |
| housenumber<mark style="color:red;">\*</mark> | Number  | 1                                                                                                                                                             |
| houseaddition                                 | String  | A                                                                                                                                                             |
| valuationdate                                 | String  | Enter as YYYYMMDD, default is TODAY. Ex: 20211230                                                                                                             |
| innersurfacearea                              | Number  | 160                                                                                                                                                           |
| buildyear                                     | Number  | 2001                                                                                                                                                          |
| housetype                                     | String  | See [page](https://docs.altum.ai/english/property-valuation-and-market/interactive-reference-api/house-types)                                                 |
| energylabel                                   | String  | A                                                                                                                                                             |
| url                                           | String  | The facade url image of the target house                                                                                                                      |
| reference\_number                             | Number  | Minimum 3 till 30                                                                                                                                             |
| strict\_street                                | Boolean | Strict search on street level                                                                                                                                 |
| strict\_buurt                                 | Boolean | Strict search on buurt level                                                                                                                                  |
| strict\_wijk                                  | Boolean | Strict search on wijk level                                                                                                                                   |
| strict\_energylabel                           | Boolean | Strict search for similar houses with this energy label                                                                                                       |
| comparable\_housetype                         | Number  | 0,1,2. Default: 0                                                                                                                                             |
| comparable\_innersurfacearea                  | Number  | 0,1,2,3. Default: 0                                                                                                                                           |
| comparable\_buildyear                         | Number  | 0,1,2,3. Default: 0                                                                                                                                           |
| comparable\_distance                          | Number  | 0,1,2. Default: 0                                                                                                                                             |
| weight\_innersurfacearea                      | Number  | Between 0 and 1. Default: 0.2                                                                                                                                 |
| weight\_buildyear                             | Number  | Between 0 and 1. Default: 0.9                                                                                                                                 |
| weight\_transactiondate                       | Number  | Between 0 and 1. Default: 0.2                                                                                                                                 |
| weight\_distance                              | Number  | Between 0 and 1. Default: 0.5                                                                                                                                 |
| weight\_visualsimilarity                      | Number  | Between 0 and 1. Default: 0.5                                                                                                                                 |
| visual\_similarity                            | Boolean | <p>0: if interested for visual similarity<br>1: if not interested for visual similarity</p>                                                                   |
| date\_limit                                   | Number  | Between 6 and 60 in months search history of transactions. Default: 60.                                                                                       |
| housetype\_to\_search                         | List    | Function to only search for given house types, see [page](https://docs.altum.ai/english/property-valuation-and-market/interactive-reference-api/house-types). |
| include\_listings                             | Boolean | <p>0: if only Kadaster references preferred<br>1: if both listing and Kadaster references preferred</p>                                                       |

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

```
{
	"GivenHouse": {
		"PostCode": "6942HE",
		"HouseNumber": 56,
		"HouseAddition": null,
		"ValuationDate": 20231125,
		"InnerSurfaceArea": 140,
		"OuterSurfaceArea": 360,
		"HouseType": "Vrijstaande woning",
		"BuildYear": 1960,
		"EnergyLabel": {
			"DefinitiveEnergyLabel": "E",
			"DefinitiveType": "NEN7120",
			"DefinitiveValidity": "2030-10"
		},
		"Image": "https://cloud.funda.nl/valentina_media/165/982/890_720x480.jpg"
	},
	"Inputs": {
		"StrictStreet": 0,
		"StrictBuurt": 0,
		"StrictWijk": 0,
		"StrictEnergyLabel": 0,
		"ComparableHouseType": 0,
		"ComparableInnerSurfaceArea": 0,
		"ComparableBuildYear": 0,
		"ComparableDistance": 0,
		"DateLimit": 60
	},
	"ReferenceData": {
		"ReferencePriceMean": "350000-375000",
		"ReferenceHouses": [
			{
				"PostCode": "6566XN",
				"HouseNumber": 2,
				"HouseAddition": null,
				"Street": "Burgemeester Reijmersstraat",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Geschakelde woning",
				"BuildYear": 1955,
				"InnerSurfaceArea": 171,
				"OuterSurfaceArea": 305,
				"Volume": 598.0,
				"DefinitiveEnergyLabel": "A",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2027-09",
				"Longitude": 6.051181765879782,
				"Latitude": 51.861647149194276,
				"Transactiondate": 201909,
				"Image": "https://cloud.funda.nl/valentina_media/085/383/417_1440.jpg",
				"TransactionPrice": "275000-300000",
				"IndexedTransactionPrice": "400000-450000",
				"PriceIndex": 128.5,
				"Distance": 10616,
				"VisualSimilarityScore": 84.178,
				"Weight": 1.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566AA",
				"HouseNumber": 9,
				"HouseAddition": null,
				"Street": "Burgemeester Hermsenstraat",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Hoekwoning",
				"BuildYear": 1971,
				"InnerSurfaceArea": 110,
				"OuterSurfaceArea": 269,
				"Volume": 385.0,
				"DefinitiveEnergyLabel": null,
				"DefinitiveType": null,
				"DefinitiveValidity": null,
				"Longitude": 6.05011576095955,
				"Latitude": 51.86221046589032,
				"Transactiondate": 202007,
				"Image": "https://cloud.funda.nl/valentina_media/127/400/732_1440x960.jpg",
				"TransactionPrice": "225000-250000",
				"IndexedTransactionPrice": "275000-300000",
				"PriceIndex": 139.2,
				"Distance": 10616,
				"VisualSimilarityScore": 82.376,
				"Weight": 0.978,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566ZT",
				"HouseNumber": 7,
				"HouseAddition": null,
				"Street": "Dennenstraat",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Hoekwoning",
				"BuildYear": 1979,
				"InnerSurfaceArea": 84,
				"OuterSurfaceArea": 203,
				"Volume": 294.0,
				"DefinitiveEnergyLabel": "C",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2028-11",
				"Longitude": 6.0548413275038975,
				"Latitude": 51.859765755682105,
				"Transactiondate": 201903,
				"Image": "https://cloud.funda.nl/valentina_media/086/290/288_1440x960.jpg",
				"TransactionPrice": "150000-175000",
				"IndexedTransactionPrice": "250000-275000",
				"PriceIndex": 124.9,
				"Distance": 10615,
				"VisualSimilarityScore": 75.15,
				"Weight": 0.891,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6942HS",
				"HouseNumber": 16,
				"HouseAddition": null,
				"Street": "Liemersweg",
				"BuurtCode": "BU19550203",
				"WijkCode": "WK195502",
				"City": "Didam",
				"HouseType": "2 onder 1 kap woning",
				"BuildYear": 1957,
				"InnerSurfaceArea": 119,
				"OuterSurfaceArea": 540,
				"Volume": 409.0,
				"DefinitiveEnergyLabel": "D",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2030-11",
				"Longitude": 6.152381715356643,
				"Latitude": 51.933182786208704,
				"Transactiondate": 202104,
				"Image": null,
				"TransactionPrice": "250000-275000",
				"IndexedTransactionPrice": "300000-325000",
				"PriceIndex": 155.4,
				"Distance": 84,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566AA",
				"HouseNumber": 5,
				"HouseAddition": null,
				"Street": "Burgemeester Hermsenstraat",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Tussenwoning",
				"BuildYear": 1971,
				"InnerSurfaceArea": 103,
				"OuterSurfaceArea": 149,
				"Volume": 363.0,
				"DefinitiveEnergyLabel": null,
				"DefinitiveType": null,
				"DefinitiveValidity": null,
				"Longitude": 6.050000952095453,
				"Latitude": 51.862300999960034,
				"Transactiondate": 201910,
				"Image": null,
				"TransactionPrice": "125000-150000",
				"IndexedTransactionPrice": "200000-225000",
				"PriceIndex": 130.3,
				"Distance": 10614,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566XD",
				"HouseNumber": 17,
				"HouseAddition": null,
				"Street": "Wethouder Koenenstraat",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "2 onder 1 kap woning",
				"BuildYear": 1948,
				"InnerSurfaceArea": 182,
				"OuterSurfaceArea": 427,
				"Volume": null,
				"DefinitiveEnergyLabel": null,
				"DefinitiveType": null,
				"DefinitiveValidity": null,
				"Longitude": 6.050890939815937,
				"Latitude": 51.86180598611541,
				"Transactiondate": 201906,
				"Image": null,
				"TransactionPrice": "175000-200000",
				"IndexedTransactionPrice": "250000-275000",
				"PriceIndex": 126.4,
				"Distance": 10615,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "7009CR",
				"HouseNumber": 30,
				"HouseAddition": null,
				"Street": "Bloemersstraat",
				"BuurtCode": "BU02220904",
				"WijkCode": "WK022209",
				"City": "Doetinchem",
				"HouseType": "Hoekwoning",
				"BuildYear": 1950,
				"InnerSurfaceArea": 128,
				"OuterSurfaceArea": 395,
				"Volume": 448.0,
				"DefinitiveEnergyLabel": "C",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2030-02",
				"Longitude": 6.2905459609860666,
				"Latitude": 51.97695144905982,
				"Transactiondate": 202008,
				"Image": null,
				"TransactionPrice": "300000-325000",
				"IndexedTransactionPrice": "400000-450000",
				"PriceIndex": 139.2,
				"Distance": 10616,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566EV",
				"HouseNumber": 140,
				"HouseAddition": null,
				"Street": "Heerbaan",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Vrijstaande woning",
				"BuildYear": 1976,
				"InnerSurfaceArea": 250,
				"OuterSurfaceArea": 843,
				"Volume": null,
				"DefinitiveEnergyLabel": "B",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2032-07",
				"Longitude": 6.04799884793402,
				"Latitude": 51.86338192770656,
				"Transactiondate": 202306,
				"Image": null,
				"TransactionPrice": "600000-650000",
				"IndexedTransactionPrice": "600000-650000",
				"PriceIndex": 182.3,
				"Distance": 10616,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "6566XA",
				"HouseNumber": 3,
				"HouseAddition": null,
				"Street": "Acaciahof",
				"BuurtCode": "BU19450900",
				"WijkCode": "WK194509",
				"City": "Millingen aan de Rijn",
				"HouseType": "Tussenwoning",
				"BuildYear": 1979,
				"InnerSurfaceArea": 106,
				"OuterSurfaceArea": 165,
				"Volume": 362.0,
				"DefinitiveEnergyLabel": "D",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2028-11",
				"Longitude": 6.055114592952519,
				"Latitude": 51.85959341801129,
				"Transactiondate": 201811,
				"Image": null,
				"TransactionPrice": "150000-175000",
				"IndexedTransactionPrice": "225000-250000",
				"PriceIndex": 123.1,
				"Distance": 10618,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			},
			{
				"PostCode": "7009CC",
				"HouseNumber": 52,
				"HouseAddition": null,
				"Street": "Zandstraat",
				"BuurtCode": "BU02220903",
				"WijkCode": "WK022209",
				"City": "Doetinchem",
				"HouseType": "Tussenwoning",
				"BuildYear": 1960,
				"InnerSurfaceArea": 112,
				"OuterSurfaceArea": 182,
				"Volume": 352.0,
				"DefinitiveEnergyLabel": "E",
				"DefinitiveType": "NEN7120",
				"DefinitiveValidity": "2030-10",
				"Longitude": 6.285970438505862,
				"Latitude": 51.98227174501624,
				"Transactiondate": 202012,
				"Image": null,
				"TransactionPrice": "175000-200000",
				"IndexedTransactionPrice": "225000-250000",
				"PriceIndex": 142.7,
				"Distance": 10623,
				"VisualSimilarityScore": null,
				"Weight": 0.0,
				"Source": "Kadaster"
			}
		]
	}
}
```

{% 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 type is unsupported.'
}

{
    'Output': 'The energy label of the given house is unknown. Please fill the energylabel input.'
}

{
    'Output': 'We do not have an image for the given house. Please fill the url input.'
}

{
    '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="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": "6631KJ",
  "housenumber": 11,
  "houseaddition": "",
  "buildyear": null,
  "innersurfacearea": null,
  "housetype": null,
  "reference_number": 30,
  "strict_street": 1,
  "strict_buurt": 0,
  "strict_wijk": 0,
  "strict_energylabel": 0,
  "date_limit": 24,
  "comparable_housetype": 1,
  "comparable_innersurfacearea": 1,
  "comparable_buildyear": 2,
  "comparable_distance": 0,
  "weight_innersurfacearea": 0.3,
  "weight_buildyear": 0.3,
  "weight_transactiondate": 0.3,
  "weight_distance": 0.3,
  "weight_visualsimilarity": 0.6,
  "housetype_to_search": [],
  "include_funda_data": 0
}
```