Kontakt über die API anlegen

In dieser Übung legst du über die API einen vollständigen Kontakt an: eine Organisation mit Adressen und einer zugehörigen Person. Das Beispiel zeigt das Zusammenspiel der beteiligten Objekte – Kontakte, Adressen und Organisationen sind in teamspace eigene Objekte, die du miteinander verknüpfst.

Das Mental-Modell vorab

Ein Organisations-Objekt organisiert Kontakte wie ein Ordner im Dateisystem – es ist selbst kein Kontakt, sondern braucht einen Hauptkontakt, der den Eintrag im Adressbuch repräsentiert.
Adressen (Post, Telefon, E-Mail) sind eigene Objekte. Ein Kontakt ist nicht auf eine feste Zahl an Adressen begrenzt – du legst so viele an, wie du brauchst, und verknüpfst sie.
Über bevorzugte Adressen (preferred addresses) lässt sich eine Person an die Adresse ihrer Organisation koppeln: Ändert sich die Firmenadresse, ändert sich automatisch auch die Arbeitsadresse der Person.

Die beteiligten Endpunkte

Schritt	Methode	Endpunkt
Organisations-Kontakt anlegen	`POST`	`/api/contact`
Adresse / Telefon / E-Mail anlegen	`POST`	`/api/contactfield`
Organisation anlegen	`POST`	`/api/organization`
Kontakt finalisieren / verknüpfen	`PUT`	`/api/contact/{id}`
Person-Kontakt anlegen	`POST`	`/api/contact`

Adressen, Telefonnummern und E-Mails sind allesamt Kontaktfelder (contactfield). Ihr value steht im vCard-Format ;;Straße;Stadt;;PLZ;Land; type ist z. B. ADR (Adresse), subtype z. B. WORK oder HOME.

Schritt für Schritt

1. Organisations-Kontakt anlegen – der Hauptkontakt, der die Organisation im Adressbuch repräsentiert (person: false):

POST /api/contact
{
  "active": true,
  "person": false,
  "lastname": "5 Point AG",
  "description": "Zentrale der 5 Point AG"
}

2. Postanschrift anlegen – als eigenes Kontaktfeld, verknüpft mit dem eben erstellten Kontakt:

POST /api/contactfield
{
  "value": ";;Rheinstraße 40-42;Darmstadt;;64283;Deutschland",
  "type": "ADR",
  "subtype": "WORK",
  "contact": {{contactCreated}}
}

3. Telefonnummer der Organisation anlegen – ebenfalls als Kontaktfeld (analog, mit passendem type).

4. Organisation anlegen – das Organisations-Objekt, das die zuvor erstellte Adresse referenziert:

POST /api/organization
{
  "name": "5Point",
  "description": "Demo-Organisation",
  "address": {{contactCreated}}
}

5. Verknüpfungen herstellen – den Organisations-Kontakt aktualisieren und mit bevorzugter Adresse (mainAddress) und Organisation verbinden:

PUT /api/contact/{{contactCreated}}
{
  "active": true,
  "person": false,
  "mainAddress": {{contactfieldCreated}},
  "organization": {{organizationCreated}}
}

6. Person-Kontakt anlegen – nun eine Person (person: true) zur bestehenden Organisation; sie übernimmt deren Adresse als bevorzugte Anschrift:

POST /api/contact
{
  "active": true,
  "person": true,
  "firstname": "Christoph",
  "lastname": "Preisser",
  "mainAddress": {{contactfieldCreated}},
  "organization": {{organizationCreated}}
}

7. E-Mail und Telefon der Person anlegen – als weitere Kontaktfelder (POST /api/contactfield), sofern die Person eigene, von der Firma abweichende Adressen hat.

Die Platzhalter {{contactCreated}}, {{contactfieldCreated}} und {{organizationCreated}} stehen für die IDs, die du aus den jeweils vorangegangenen Antworten übernimmst.

Hinweise

Wer für die Person die Firmenadresse als bevorzugte Postanschrift übernimmt, hält sie automatisch aktuell: Eine Änderung der Firmenadresse wirkt sich direkt auf die Arbeitsadresse der Person aus. Für E-Mail und Telefon gilt dasselbe Prinzip – nutze eigene Adressen nur dort, wo die Person tatsächlich abweicht.
Die Adressen werden zuerst angelegt und anschließend mit dem Kontakt verknüpft – nicht umgekehrt. Plane die Reihenfolge entsprechend, wenn du den Ablauf automatisierst.
Welche URL welche Collection anspricht (contact, Adressen, Organisation), klärt die URL-Struktur.