# Authentication, input and response

## Transaction API

{% tabs %}
{% tab title="V1" %} <mark style="color:green;">`POST`</mark> `https://api.altum.ai/transaction`

This endpoint allows you to retrieve Kadaster transaction data for an object.

#### 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                                 | number | 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="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."
}
```

{% 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="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 %}

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

```
{
  "Output": [
    {
      "Transaction": "Transaction-20100315",
      "BagID": null,
      "PostCode": "2771HM",
      "HouseNumber": 173,
      "HouseAddition": null,
      "City": "BOSKOOP",
      "Street": "PARKLAAN",
      "HouseType": "T",
      "BuildingCode": 11,
      "OuterSurfaceArea": 315,
      "MoreRealEstate": "J",
      "RentedOut": "J",
      "BusinessRight": "VE",
      "MutationVariety": 606,
      "FamilyTransaction": "N",
      "TransactionDate": 20191001,
      "TransactionPrice": 500000,
      "TransactionPriceIndexed": 600000
    }
  ]
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="V2" %} <mark style="color:green;">`POST`</mark> `https://api.altum.ai/v2/transaction`

This endpoint allows you to retrieve Kadaster transaction data for an object. The price is indexed to the current date.

#### 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                                                        |
| housenumber<mark style="color:red;">\*</mark> | number | House number of the object                                                   |
| houseaddition                                 | string | House letter and addition of the object                                      |
| valuation\_date                               | number | Enter as YYYYMMDD, gives newest transaction till that date. Default is TODAY |

{% tabs %}
{% 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."
}
```

{% 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="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 %}

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

```
{
    "transaction": "Transaction-20100315",
    "bag_id": null,
    "postcode": "2771HM",
    "housenumber": 173,
    "houseaddition": null,
    "city": "BOSKOOP",
    "street": "PARKLAAN",
    "house_type": "T",
    "building_code": 11,
    "outer_surface_area": 315,
    "more_real_estate": "J",
    "rented_out": "J",
    "business_right": "VE",
    "mutation_variety": 606,
    "family_transaction": "N",
    "buyer": "BV",
    "seller": null,
    "transaction_date": 20191001,
    "transaction_price": 500000,
    "transaction_price_indexed": 600000
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## FREE Ping for availability

## Post object data to receive availability of transaction data

{% tabs %}
{% tab title="V1" %} <mark style="color:green;">`POST`</mark> `https://api.altum.ai/transaction/ping`

This endpoint allows you to get the availability of the transaction data from our database. A POST request requires a body parameter (Address).

#### Headers

| Name                                        | Type   | Description                                                          |
| ------------------------------------------- | ------ | -------------------------------------------------------------------- |
| x-api-key<mark style="color:red;">\*</mark> | string | 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                                 | number | 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="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="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 %}

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

```
{
	"Output": "Transaction Data for 2728KH-8- is available.",
	"Date": "20210602"
}
```

{% endtab %}
{% endtabs %}

## Request body

#### Example request

```
{
	"postcode": "2728KH",
	"housenumber": 5
}
```

{% endtab %}

{% tab title="V2" %} <mark style="color:green;">`POST`</mark> `https://api.altum.ai/v2/transaction/ping`

This endpoint allows you to get the availability of the transaction data from our database. A POST request requires a body parameter (Address).

{% hint style="info" %}
Ping V2 queries the Transaction API V2 database. Please use Transaction API V2 with Ping V2.
{% endhint %}

#### Headers

| Name                                        | Type   | Description                                                          |
| ------------------------------------------- | ------ | -------------------------------------------------------------------- |
| x-api-key<mark style="color:red;">\*</mark> | string | 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                                                        |
| housenumber<mark style="color:red;">\*</mark> | number | House number of the object                                                   |
| houseaddition                                 | string | House letter and addition of the object                                      |
| valuation\_date                               | number | Enter as YYYYMMDD, gives newest transaction till that date. Default is TODAY |

{% tabs %}
{% 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="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 %}

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

```
{
	"output": "Transaction Data for 2728KH-8- is available.",
	"date": "20210602"
}
```

{% endtab %}
{% endtabs %}

## Request body

#### Example request

```
{
	"postcode": "2728KH",
	"housenumber": 5
}
```

{% endtab %}
{% endtabs %}