# Einführung

## API V2 Documentation <a href="#anwendungsf-lle" id="anwendungsf-lle"></a>

Die Dokumenation für API V2 finden Sie [hier](https://api.propstack.de/docs/index.html).

## Anwendungsfälle <a href="#anwendungsf-lle" id="anwendungsf-lle"></a>

Sie können diese API verwenden, um zum Beispiel:

* Homepage mit aktuellen Einheiten/Projekten darzustellen.
* Auswertungen ihrer Kontakte zu machen.
* Backups ihrer wichtigen Daten zu erstellen.

## Fragen / Probleme

Wenn es Fragen oder Probleme zur API von Propstack gibt, senden Sie gerne eine E-Mail an <developers@propstack.de>. Präferierte Sprache im Entwickler-Team ist Englisch. :)

## Basis URL <a href="#basis-url" id="basis-url"></a>

Alle Endpunkte haben folgende Basis-URL.

```
https://api.propstack.de/v1
```

## Authentication <a href="#authentication" id="authentication"></a>

Um Anfragen auf die API machen zu können, braucht es einen API-Schlüssel. Jeder Account in Propstack kann nur einen Schlüssel haben. Dieser Schlüssel muss in jeder Abfrage mitgesendet werden. Dies kann durch 2 Wege passieren:

#### URL mit api\_key als Parameter

```
https://api.propstack.de/v1/brokers?api_key=mein_api_key
```

Die erste Möglichkeit funktioniert über einen Parameter `api_key` in der URL.

#### URL mit X-API-KEY im Header

```
$ curl https://api.propstack.de/v1/brokers -H "X-API-KEY: mein_api_key"
```

Die zweite Möglichkeit nutzt einen Header `X-API-KEY`.

## FAQ: Oft gestellte Fragen

Hier finden Sie einen Überblick über oft gestellte Fragen und Antworten.

<details>

<summary>Wie erstelle ich einen API Key oder finde einen bestehenden API Key? </summary>

In Propstack findet sich die Verwaltung der API Keys in **Verwaltung -> API-Schlüssel** <https://crm.propstack.de/app/admin/api_keys> \
\
Hier können Sie API-Schlüssel für unsere API V1 oder V2 erstellen und ihre Berechtigungen editieren. Hier können Sie auch Logs der API-Keys aufrufen und sehen, in welchen Requests diese verwendet wurden.

</details>

<details>

<summary>Ich entwickle im Auftrag der Firma XY eine Integration. Können Sie mir einen API Key bereitstellen?</summary>

Aus Sicherheitsgründen können wir Ihnen leider keinen API-Key bereitstellen. Bitte setzen Sie sich mit einem Admin Ihrer/Ihres Auftragsgberin/Auftraggebers in Verbindung, um einen API-Key mit den benötigten Berechtigungen zu erhalten.

</details>

<details>

<summary>Welche Unterschiede gibt es zwischen API V1 und API V2?</summary>

API V2 ist aktuell noch in Arbeit. Es sind nicht alle V1-Endpunkte in V2 abgebildet. Allgemein, aber ist V2 bei Abfrage großer Datenmengen mit den Scroll-Endpunkten effizienter. Abhängig von Ihrem Anwendungszweck ist es sinnvoll, beide API Versionen zu verwenden.

</details>

<details>

<summary>Wie verbinde ich meine Website mit Propstack?</summary>

Es gibt mehrere Möglichkeiten, Anfragen von Ihrer Website an Propstack zu übermitteln, nachdem ein Kunde ein Formular ausgefüllt hat:

* **E-Mail mit XML-Anhang**: Sie können die Kundendaten aus ihrem Formular in einer XML-Datei als Anhang via E-Mail an ein in Propstack angebundenes Postfach versenden. Sofern die E-Mail-Adresse des Absenders als Kontaktquelle (<https://crm.propstack.de/app/admin/settings/contacts>) hinterlegt ist, wird diese E-Mail automatisch als Portalanfrage erkannt und kann für eine Automatisierung verwendet werden.
* **Formatierte E-Mail**: Alternativ können Sie die Kundendaten in einer formatierten E-Mail senden. Auch hier muss die Kontaktquelle definiert sein, damit eine Automatisierung ausgelöst werden kann.
* **API-Request**: Hierbei müssen Sie zunächst einen Kontakt anlege und anschließend eine Notiz mit der ID der Kontaktquelle in `client_source_id` setzen. Beim Erstellen dieser Notiz wird dann ein Portalanfrage Trigger für die Automatisierungen ausgelöst.

Eine technische Beschreibungen zu diesen Formaten findet sich hier: <https://docs.propstack.de/webseite/anfragen>

</details>

<details>

<summary>Wie erstelle ich Suchprofile über die API?</summary>

Es gibt in Propstack die Möglichkeit, Suchprofile über die API anzulegen. Dafür müssen Kontakt und Objekt bereits bestehen. Eine techinische Beschreibung der notwendigen Felder finden Sie hier:  <https://docs.propstack.de/reference/suchprofile>

</details>

<details>

<summary>Wie setze ich Custom Felder bei Kontakten oder Objekten?</summary>

Wenn Sie Objekte oder Kontakte via API erstellen oder aktualisieren, können Sie auch Custom Felder setzen. Verwenden Sie dafür am besten das Feld `partial_custom_fields`  im Payload wie hier beschrieben: <https://docs.propstack.de/reference/kontakte#kontakt-erstellen-mit-custom-feldern>\
\
Eine technische Beschreibung zum Erstellen/Lesen von Custom Feldern finden sie hier: <https://docs.propstack.de/reference/custom-felder><br>

</details>

<details>

<summary>Feld XY fehlt auf einem API Endpunkt</summary>

Wir versuchen alle relevanten Felder auf einem Endpunkt bereitzustellen. Falls Sie ein Feld vermissen, können Sie bei Objekten den URL-Parameter `new=1` verwenden. Hierüber haben Sie Zugriff auf weitere Felder. \
\
Ansonsten schreiben Sie uns gerne eine E-Mail an <developers@propstack.de>, wenn sie ein Feld vermissen.

</details>


---

# 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.propstack.de/master.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.