Kontakt anlegen oder aktualisieren (Upsert)

POST /contacts/upsert

Dies ist die bevorzugte Methode, um einen Kontakt zu erstellen oder zu aktualisieren. Das System sucht automatisch anhand von E-Mail oder Telefonnummer nach einem Duplikat.

Logik des Endpunkts (Update oder Insert):

Dieser Endpunkt folgt den "Duplikats-Einstellungen" deines Standorts. Standardmäßig gilt:

Fall 1 (Update): Ein Kontakt mit der E-Mail ODER der Telefonnummer existiert bereits. Der bestehende Kontakt wird mit den neuen Daten aktualisiert.
Fall 2 (Insert): Kein Kontakt wird gefunden. Ein neuer Kontakt wird angelegt.

In beiden Fällen erhältst du die contactId zurück.

Erforderliche Header

Authorization: Bearer {{ token }}
Content-Type: application/json
Version: 2021-07-28

Request Body (Anfrage)

Sende alle Informationen, die du über den Kontakt hast. email oder phone sind entscheidend für die Duplikatsprüfung.

{
  // --- Wichtige Felder für Duplikatsprüfung ---
  "email": "[email protected]",
  "phone": "+49123456789",

  // --- Grundlegende Kontaktinfos ---
  "firstName": "Max",
  "lastName": "Mustermann",
  "name": "Max Mustermann", // Wird oft automatisch aus firstName/lastName generiert
  
  // --- Standort & Adresse ---
  // Die Location ID, die du auch für andere Abfragen nutzt.
  "locationId": "UFeZwU5X6PIJLwU2XO3k",
  "address1": "Musterstraße 1",
  "city": "Berlin",
  "state": "Berlin",
  "postalCode": "10115",
  "country": "DE", // ISO 3166-1 Alpha-2 Code

  // --- Optionale Felder ---
  "tags": [
    "telefonisch-gebucht",
    "deskbot-patient"
  ],
  "source": "DeskBot Anruf",
  
  // Optional: Einem bestimmten User zuweisen (die 'userId' von SOKAI)
  "assignedTo": "15tDtK9qqUdfHTtrL5np",

  // --- Custom Fields (Detailliertes Format) ---
  // HINWEIS: Du musst die 'key' (oder 'id') deiner Custom Fields kennen.
  // 'verordnung_id' ist nur ein BEISPIEL-Key.
  "customFields": [
    {
      // Entweder 'id' ODER 'key' des Feldes angeben
      "key": "verordnung_id", 
      "field_value": "VO-12345"
    }
  ]
}

Mögliche Antworten (Response)

Antwort (200 OK): Kontakt erstellt/aktualisiert

Die Antwort enthält das vollständige Kontaktobjekt, einschließlich der id (Contact ID).

{
  "contact": {
    "id": "a1b2c3d4e5f6g7h8i9j0",
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "[email protected]",
    "phone": "+49123456789",
    "address1": "Musterstraße 1",
    "city": "Berlin",
    "tags": [
      "telefonisch-gebucht",
      "deskbot-patient"
    ],
    "customFields": [
      {
        "id": "CUSTOM_FIELD_ID_XYZ",
        "key": "verordnung_id",
        "field_value": "VO-12345"
      }
    ],
    "dateAdded": "2025-10-20T10:30:00.000Z"
    // ... und viele weitere Felder
  }
}