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

![](https://1172273446-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lw4gk5ARKsgVHFCdPZw%2F-MdM2SJANrI6T2bHn0pv%2F-MdM4I3wCEr6Wxau7hNL%2FReqbin.PNG?alt=media\&token=8bbf815f-0a99-4a02-bdd2-273b9d001ab3)

### 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" %}

![](https://1172273446-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lw4gk5ARKsgVHFCdPZw%2Fuploads%2FbfNentfAYLN5s9BYNwJn%2Fsust-api-call.png?alt=media\&token=d59e5b95-2ea1-4f88-b782-bc8f51de5ab7)
{% 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" %}
![](https://1172273446-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lw4gk5ARKsgVHFCdPZw%2F-MdQqjX5dBqix7ie8IiQ%2F-MdQsJsj6xjtDIVaIIJd%2FPostman-request.JPG?alt=media\&token=ca071c3d-fef0-46e0-98bb-9611795f32df)
{% endtab %}

{% tab title="Headers" %}
![](https://1172273446-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lw4gk5ARKsgVHFCdPZw%2F-MdQqjX5dBqix7ie8IiQ%2F-MdQsMN2RWUKYsChae0w%2FPostman-headers.JPG?alt=media\&token=e4cac65f-3b93-462a-8eae-513a573e449a)
{% endtab %}

{% tab title="Body" %}
![](https://1172273446-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lw4gk5ARKsgVHFCdPZw%2F-MdQqjX5dBqix7ie8IiQ%2F-MdQsOzeeIq5JTjfreZU%2FPostman-body.JPG?alt=media\&token=3a273d48-f215-4401-a45b-8666c0a6a915)
{% endtab %}
{% endtabs %}