# Perform your first API call

### Tip! Use the following applications

Anchor link to the article.

* [Reqbin.com](https://docs.altum.ai/setting-up-an-api-call#performing-a-request-in-reqbin-com)
* [Insomnia](https://docs.altum.ai/setting-up-an-api-call#performing-a-request-in-insomnia)
* [Postman](https://docs.altum.ai/setting-up-an-api-call#performing-a-request-in-postman)

### OpenAPI specification

Perform a GET request to the API endpoint of choice with '/openapi' amended to retrieve the OpenAPI specification for the given API.\
\
**Example**:

## OpenAPI specification for AVM API

<mark style="color:blue;">`GET`</mark> `https://api.altum.ai/avm/openapi`

{% tabs %}
{% tab title="200: OK OpenAPI specification" %}

```
{
	"openapi": "3.0.2",
	"info": {
		"title": "AVM API",
		"description": "Predicts the transaction value for a given house address.",
		"version": "2.0"
	},
	"paths": {
		"/predict": {
			"post": {
				"tags": [
					"AVM API"
				],
				"summary": "Displays the AVM data as well as the prediction.",
				"operationId": "output_predict_post",
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/AVM"
							}
						}
					},
					"required": true
				},
				"responses": {
					"200": {
						"description": "Prediction for the given house address.",
						"content": {
							"application/json": {
								"schema": {},
								"example": {
									"Output": {
										"BagID": "str",
										"PostCode": "str",
										"HouseNumber": "int",
										"HouseAddition": "str",
										"City": "str",
										"Street": "str",
										"HouseType": "str",
										"BuildYear": "int",
										"InnerSurfaceArea": "int",
										"OuterSurfaceArea": "int",
										"Volume": "int",
										"EnergyLabel": "str",
										"Longitude": "float",
										"Latitude": "float",
										"Rooms": "int",
										"Image": "str",
										"ValuationDate": "int",
										"PriceEstimation": "int",
										"Confidence": "str",
										"AccuracyIndicator": "int or str"
									}
								}
							}
						}
					},
					"400": {
						"description": "The given house address was not found in database.",
						"content": {
							"application/json": {
								"example": [
									"Output: The given house address was not found in database."
								]
							}
						}
					},
					"422": {
						"description": "Validation Error.",
						"content": {
							"application/json": {
								"example": {
									"detail": [
										{
											"loc": [
												"query",
												"housenumber"
											],
											"msg": "ensure this value is greater than 0",
											"type": "value_error.number.not_gt",
											"ctx": {
												"limit_value": 0
											}
										}
									]
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"schemas": {
			"AVM": {
				"title": "AVM",
				"required": [
					"postcode",
					"housenumber"
				],
				"type": "object",
				"properties": {
					"postcode": {
						"title": "Postcode of the given house.",
						"pattern": "^(?!1000|1001|1002|1003|1004|1005|1006|1007|1008|1009|1010)[1-9][0-9]{3}[A-Z]{2}$",
						"type": "string",
						"example": "1234AB"
					},
					"housenumber": {
						"title": "House number of the given house.",
						"exclusiveMinimum": 0.0,
						"type": "integer",
						"example": 1
					},
					"houseaddition": {
						"title": "House addition of the given house.",
						"type": "string",
						"default": ""
					},
					"valuationdate": {
						"title": "Date of evaluation.",
						"type": "string",
						"format": "date",
						"default": "20230410"
					},
					"buildyear": {
						"title": "Buildyear",
						"maximum": 2023.0,
						"minimum": 1800.0,
						"type": "integer"
					},
					"innersurfacearea": {
						"title": "Innersurfacearea",
						"exclusiveMinimum": 0.0,
						"type": "number"
					},
					"outersurfacearea": {
						"title": "Outersurfacearea",
						"exclusiveMinimum": 0.0,
						"type": "number"
					},
					"housetype": {
						"title": "Housetype",
						"enum": [
							"Vrijstaande woning",
							"2 onder 1 kap woning",
							"Geschakelde 2 onder 1 kapwoning",
							"Geschakelde woning",
							"Tussen/rijwoning",
							"Hoekwoning",
							"Eindwoning",
							"Galerijflat",
							"Portiekflat",
							"Corridorflat",
							"Maisonnette",
							"Benedenwoning",
							"Bovenwoning",
							"Portiekwoning"
						],
						"type": "string"
					},
					"energylabel": {
						"title": "Energylabel",
						"enum": [
							"G",
							"F",
							"E",
							"D",
							"C",
							"B",
							"A",
							"A+",
							"A++",
							"A+++",
							"A++++",
							"A+++++"
						],
						"type": "string"
					},
					"image": {
						"title": "Image",
						"enum": [
							0,
							1
						],
						"type": "integer",
						"default": 0
					}
				}
			}
		}
	}
}
```

{% endtab %}
{% endtabs %}

## Performing a request in Reqbin.com

Go to [Reqbin.com](https://reqbin.com/) and add the endpoint URL in the URL-box. Depending on the API, select a POST or GET request. Be sure to select "DE" or "EXT" as the server for faster processed requests.\
\
Add the message / request in the **Content** tab. Add the *x-api-key* header for authentication to the **Headers** tab.

Press "send" to perform the request.

{% code title="Curl/Bash" %}

```bash
#!/bin/bash

curl -X POST https://api.altum.ai/sandbox/avm -H "x-api-key: m2ipzWVV3e9yPU9TduqpY4oZTbcEHCGj31GLVLYB" -H "Content-Type: application/json" --data-binary @- <<DATA
{
   "postcode" : "1234AB",
   "housenumber" : "1"
}
DATA
```

{% endcode %}

![](/files/-MdM4I3wCEr6Wxau7hNL)

### Performing a request in Insomnia

Download and install the free program [Insomnia](https://insomnia.rest/download). Create a new 'Request collection'. Add a 'New Request' (CTRL + N) and gives this request a name. Select POST or GET depending on the API and use JSON for the Body Text when Posting.

Add the endpoint URL of the API behind the POST/GET function into the endpoint URL box. Then add the JSON message to the JSON entry field. Lastly, configure the headers to include the Content-Type and the x-api-key for authentication and press "Send".

{% tabs %}
{% tab title="Message" %}

![](/files/F9EiDxkBYuuFS0sway0D)
{% endtab %}
{% endtabs %}

```bash
curl --request POST \
  --url https://api.altum.ai/sustainability \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: m2ipzWVV3e9yPU9TduqpY4oZTbcEHCGj31GLVLYB' \
  --data '{
  "data": {
    "lock_measures": {
      "lock": [
        "wall_insulation"
      ]
    },
    "max_investment": 20000,
    "gas_usage": 3000,
    "post_code": "2771DS",
    "house_number": "87",
    "target_label": "A",
    "inner_surface_area": 130,
    "inhabitants": 3,
    "replace_boiler": true,
    "heat_pump_allowed": true,
    "search_criteria": 1,
    "search_options": 2,
    "house-type": 1,
    "natural_gas": 0,
    "solar_panels_surface": 1,
    "watt_panels": true,
    "wall_insulation": 1,
    "roof_insulation": 1,
    "floor_insulation": 1,
    "living_room_windows": 1,
    "bedroom_windows": 1,
    "installation": 4,
    "shower": 0,
    "ventilation": 0,
    "solar_panels": 10
  }
}'
```

### Performing a request in Postman

Download the [Postman](https://www.postman.com/downloads/) app. Create a new HTTP Request. Select the method GET or POST depending on the API and add the endpoint URL.\
Set authorization to No Auth.&#x20;

Add the x-api-key header and API key for authentication. Set the Body to raw and JSON when performing a POST request. Press "Send"

{% tabs %}
{% tab title="Request" %}
![](/files/-MdQsJsj6xjtDIVaIIJd)
{% endtab %}

{% tab title="Headers" %}
![](/files/-MdQsMN2RWUKYsChae0w)
{% endtab %}

{% tab title="Body" %}
![](/files/-MdQsOzeeIq5JTjfreZU)
{% 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/developers/setting-up-an-api-call.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.