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