🚀 Jetzt neu: FlowAI! Ein revolutionärer Chat mit personalisierten AI-Agenten. 🌟

FlowContacts API - für persönliche Verbindungen

Eine moderne REST API zur Verwaltung von privaten Kontakten, Timeline-Einträgen und persönlichen Details. Perfekt für Integrationen, Daten-Synchronisation und individuelle Beziehungs-Management-Tools.

🔐 Schnellstart

Basis-URL: https://creativeskyline.de/api/flowcontacts/contacts
Pro-Abonnement erforderlich
Die FlowContacts API ist ausschließlich für Workspaces mit aktivem Pro-Abonnement verfügbar.

API-Zugangsdaten abrufen

Bevor Sie die API nutzen können, benötigen Sie Ihre persönlichen Zugangsdaten:

  1. Melden Sie sich in Ihrem Account an
  2. Navigieren Sie zu Profil → API-Zugang
  3. Ihr persönlicher API-Key (pk_...) ist dort direkt sichtbar und einsatzbereit

Authentifizierung

Alle API-Anfragen benötigen diese HTTP-Header:

Authorization: Bearer pk_dein_api_key
Accept: application/json

📚 API-Referenz

Basis-URL: https://creativeskyline.de/api/flowcontacts/contacts
Numerische IDs im Pfad laufen aus
Alle Detail-Endpunkte akzeptieren den Pfadwert derzeit sowohl als UUID als auch als numerische ID. Die numerische Form existiert nur noch als Übergangslösung für die FlowContacts-App und wird ohne weitere Ankündigung entfernt, sobald die App auf UUIDs umgestellt ist. Bitte ausschließlich UUIDs verwenden. Das Feld id in den Antworten ist aus demselben Grund vorübergehend wieder enthalten und gilt ebenfalls als veraltet.

Kontakte auflisten

GET /api/flowcontacts/contacts

Ruft eine Liste Ihrer persönlichen Kontakte ab. Die Antwort enthält alle verknüpften Daten wie E-Mails, Telefonnummern und Adressen.

Query-Parameter:

status string Filter nach Status: active, archived, all
search string Suchbegriff (Name, Firma, Job, E-Mail)
per_page integer Anzahl der Ergebnisse (max 200)

Kontakt-Details abrufen

GET /api/flowcontacts/contacts/{uuid}

Ruft die vollständigen Details eines einzelnen Kontakts ab, inklusive E-Mails, Telefonnummern und Adressen. Empfohlener Weg ist die Adressierung per UUID. Übergangsweise wird zusätzlich die numerische ID akzeptiert (/api/flowcontacts/contacts/123) – dieser Weg ist veraltet und läuft aus, sobald die FlowContacts-App vollständig auf UUIDs umgestellt ist. Neue Integrationen dürfen ausschließlich UUIDs verwenden. Die Antwort enthält neben uuid übergangsweise wieder das Feld id; Unterobjekte (E-Mails, Telefonnummern, Adressen) tragen weiterhin keine IDs.

Kontakt erstellen

POST /api/flowcontacts/contacts

Erstellt einen neuen privaten Kontakt. Breaking Change: Die frühere Upsert-Semantik über eine uuid im Body existiert nicht mehr; Aktualisierungen laufen über PUT /api/flowcontacts/contacts/{uuid}.

Request Body:

first_name string Vorname
last_name string Nachname
company string Firma
job_title string Berufsbezeichnung
email_addresses array Array aus E-Mail-Objekten mit label, address und is_primary
phone_numbers array Array aus Telefon-Objekten mit label, number und is_primary

Kontakt aktualisieren

PUT /api/flowcontacts/contacts/{uuid}

Aktualisiert einen bestehenden Kontakt per UUID (Teil-Update: nur gesendete Felder werden geschrieben). Übergangsweise wird auch die numerische ID im Pfad akzeptiert; dieser Weg ist veraltet und läuft aus. Ein unbekannter oder fremder Pfadwert ergibt in beiden Formen HTTP 404.

Request Body:

first_name string Vorname
last_name string Nachname
company string Firma
job_title string Berufsbezeichnung
email_addresses array Array aus E-Mail-Objekten mit label, address und is_primary
phone_numbers array Array aus Telefon-Objekten mit label, number und is_primary

Kontakt löschen

DELETE /api/flowcontacts/contacts/{uuid}

Löscht einen Kontakt per UUID (Soft-Delete). Übergangsweise wird auch die numerische ID im Pfad akzeptiert; dieser Weg ist veraltet und läuft aus. Ein unbekannter oder fremder Pfadwert ergibt in beiden Formen HTTP 404.

Profilbild hochladen

POST /api/flowcontacts/contacts/{uuid}/avatar

Lädt das Profilbild eines Kontakts als multipart/form-data hoch und ersetzt ein vorhandenes Bild. Das Bild wird serverseitig auf 500×500 Pixel zugeschnitten und als JPEG gespeichert, ein zuvor hinterlegtes Bild wird entfernt. Erlaubt sind JPEG, PNG und WebP bis 8 MB. HEIC und HEIF werden nicht unterstützt – iOS-Clients konvertieren vor dem Upload nach JPEG. Profilbilder sind bewusst nicht Teil des Sync-Push-Protokolls; Änderungen erkennen Clients über avatar_sha1 im Sync-Pull.

Request Body:

avatar file * Bilddatei als multipart/form-data-Feld (JPEG, PNG oder WebP, max. 8 MB)

Profilbild abrufen

GET /api/flowcontacts/contacts/{uuid}/avatar BINARY

Liefert die Bilddaten des Profilbilds, in der Regel als image/jpeg. Die Antwort trägt einen ETag mit dem SHA-1 der Bytes; ein Aufruf mit If-None-Match wird mit 304 Not Modified ohne Inhalt beantwortet. Externe Profilbilder, etwa aus Google Kontakte, werden per 302 auf ihre Original-URL weitergeleitet. Ohne hinterlegtes Bild antwortet der Endpunkt mit 404. Wichtig: die URL ist wie jeder andere Endpunkt tokengeschützt – sie muss mit dem Authorization-Header abgerufen werden und funktioniert nicht in einem einfachen Bild-Tag.

Profilbild löschen

DELETE /api/flowcontacts/contacts/{uuid}/avatar

Entfernt das Profilbild des Kontakts samt gespeicherter Datei. Der Aufruf ist idempotent: auch ohne hinterlegtes Bild antwortet der Server mit 204 No Content.

💻 Code-Beispiele

Basis-URL: https://creativeskyline.de/api/flowcontacts/contacts

Kompletten Kontakt anlegen

curl -X POST "BASE_URL/api/flowcontacts/contacts" \
  -H "Authorization: Bearer pk_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Erika",
    "last_name": "Mustermann",
    "job_title": "Designerin",
    "email_addresses": [
      { "label": "Geschäftlich", "address": "erika@muster.de" }
    ]
  }'

Profilbild hochladen und abrufen

curl -X POST "BASE_URL/api/flowcontacts/contacts/{uuid}/avatar" \
  -H "Authorization: Bearer pk_dein_api_key" \
  -F "avatar=@profilbild.jpg"

# Bytes abrufen (Header ist Pflicht, auch fuer das Bild selbst)
curl "BASE_URL/api/flowcontacts/contacts/{uuid}/avatar" \
  -H "Authorization: Bearer pk_dein_api_key" \
  -o profilbild.jpg

# Nur laden, wenn sich das Bild geaendert hat
curl "BASE_URL/api/flowcontacts/contacts/{uuid}/avatar" \
  -H "Authorization: Bearer pk_dein_api_key" \
  -H 'If-None-Match: "<avatar_sha1>"'