SMOC Public Contacts API — Integrationsanleitung

Leitfaden zur SMOC Public Contacts API — ein schreibgeschützter REST-Endpunkt zum Auflisten von Kontakten und aggregierten Zählwerten für Ihr Unternehmen. Nutzen Sie ihn für eigene Integrationen, Synchronisierungsjobs oder zusammen mit der Zapier-App.

Überblick

Die SMOC Public API ermöglicht es Drittsystemen, Kontakte für ein einzelnes Unternehmen auszulesen. Sie wird auf Cloudflare Workers gehostet und automatisch auf das Unternehmen beschränkt, das mit Ihrem API-Schlüssel verknüpft ist.

Aktueller Funktionsumfang:

• Listet Kontakte Ihres Unternehmens auf (bis zu 500 pro Anfrage)
• Gibt aggregierte Zählwerte für Leads und Kunden zurück
• Beschränkt Daten automatisch auf das Unternehmen, das mit Ihrem API-Schlüssel verknüpft ist

Nicht enthalten:

• Kontakte erstellen, aktualisieren oder löschen
• Paginierung mit Cursors oder Offsets (nur ein limit-Limit)
• Abfragen über mehrere Unternehmen mit einem Schlüssel

Dieser Zapier/Kompatibilitätsvertrag bleibt bestehen. Der einzige Kontakte-Endpunkt für diesen Vertrag ist:

GET /api/company/mongocontact

Erweiterte Kontaktsuche ist zusätzlich möglich: POST /api/v2/contacts_search. Migrieren Sie Zapier nicht von mongocontact weg.

Für die Einrichtung in der Console, Authentifizierung und einen Funktionsüberblick starten Sie mit dem REST API-Verbindungsleitfaden.

Ihren API-Schlüssel erhalten

Alle SMOC Datenintegrationen verwenden das gleiche Console-Token-Muster wie Zapier und MCP:

1. Melden Sie sich in der SMOC Console an.
2. Gehen Sie zu Einstellungen → Integrationen → API (für Zapier-spezifische Einrichtung Integrationen → Zapier verwenden).
3. Optional benennen Sie den Schlüssel und setzen ein Ablaufdatum, dann klicken Sie auf Neuen API-Schlüssel generieren.
4. Kopieren Sie den Schlüssel sofort — er wird nur einmal angezeigt und kann später nicht mehr abgerufen werden.

Das Generieren eines neuen Schlüssels widerruft nicht bestehende Schlüssel. Ausgestellte Schlüssel werden auf derselben Seite aufgelistet — widerrufen Sie nicht verwendete Schlüssel dort, wenn Sie Zugangsdaten rotieren müssen.

Jeder Schlüssel ist an ein Unternehmen gebunden. Der Schlüssel enthält einen operatorId-Claim, der der ID dieses Unternehmens entspricht. Die API verwendet diesen Wert, um alle Kontaktdaten zu beschränken — Sie können keine andere Unternehmens-ID in der Anfrage übergeben.

Basis-URLs

Umgebung	Basis-URL
Produktion	https://api.smoc.ai

Beispiel für einen vollständigen Endpunkt:

GET https://api.smoc.ai/api/company/mongocontact

Authentifizierung

Senden Sie Ihren API-Schlüssel in einem benutzerdefinierten HTTP-Header namens token:

GET /api/company/mongocontact HTTP/1.1
Host: api.smoc.ai
token: <your-api-key>
Content-Type: application/json

Die API prüft den Schlüssel und liest den operatorId-Claim, um zu bestimmen, welche Unternehmenskontakte zurückgegeben werden. Sie senden keine Unternehmens-ID in der URL oder im Query-String.

Nicht verwenden:

• Authorization: Bearer … — dieser Header wird von diesem Endpunkt nicht akzeptiert (auch wenn die Console-Seite "API Access" derzeit etwas anderes anzeigt). Verwenden Sie den token-Header in Integrationen, bis Produktsupport für Bearer hinzugefügt wird.
• Clerk-Secret-Keys (sk_…) oder Publishable Keys (pk_…) — diese werden mit 401 Invalid token type abgelehnt.

Anfrage

Methode: Nur GET. Andere Methoden (z. B. POST) liefern 404 Not Found.

Query-Parameter

Parameter	Typ	Erforderlich	Standard	Beschreibung
limit	integer	Nein	100	Maximale Anzahl zurückzugebender Kontakte. Muss zwischen 1–500 liegen.
sortByField	string	Nein	(keiner)	Kontakte absteigend nach diesem Feld sortieren.
status	string	Nein	(keiner)	Nach Kontaktstatus filtern. status=1 ist die Standard-Lead-Abfrage, einschließlich positiver Nachrichtenablauf-Smart-Leads.

Erlaubte sortByField-Werte:

Wert	Sortiert nach
createdAt	Erstellungsdatum des Kontakts. Wenn diese Sortierung angefordert wird (und status ausgelassen oder 1 ist), werden aktuelle späte Smart-Leads der letzten 14 Tage eingefügt und die Seite wird nach max(createdAt, leadCapturedAt) neu sortiert, sodass sie erscheinen, ohne neuere Web-Kontakte zu verdrängen.
updatedAt	Letztes Aktualisierungsdatum
lastConversationDate	Datum des letzten Gesprächs
leadCapturedAt	Wann der Kontakt ein Smart Lead wurde (fällt für historische Einträge auf updatedAt zurück)
companyUsers.lastConversationDate	Veraltetes Alias für lastConversationDate (Zapier-Kompatibilität)

Die Sortierung ist immer absteigend (neueste/höchste zuerst). Wird sie ausgelassen, wird die natürliche Reihenfolge von MongoDB verwendet.

Antwort

Erfolg (200 OK)

{
  "data": [ /* array of contact objects */ ],
  "leadsCount": 42,
  "customerCount": 18
}

Feld	Typ	Beschreibung
data	array	Kontakt-Datensätze Ihres Unternehmens
leadsCount	number	Kontakte mit Status "1" oder null
customerCount	number	Kontakte mit Status "2"

leadsCount und customerCount beziehen sich auf alle Kontakte des Unternehmens, nicht nur auf die aktuelle Seite.

Kontaktobjekt-Felder

Jedes Element in data enthält nur die unten aufgeführten Felder (sensible/interne Felder sind ausgeschlossen):

Feld	Beschreibung
id	Zapier-Poll-Identität. Meistens die Mongo _id. Spät konvertierende Smart-Leads (leadCapturedAt mindestens 1 Stunde nach createdAt und am oder nach dem 11.09.2026) verwenden {mongoId}__sl, damit New Contact ausgelöst werden kann. Verwenden Sie contactId für die stabile Mongo-ID.
contactId	Stabile Mongo _id. Ändert sich nicht, wenn id für einen späten Smart Lead neu geschrieben wird.
linkedinUrl	LinkedIn-Profil-URL, falls vorhanden (oberstes linkedinUrl oder das erste linkedinProfiles[].url).
userId	Benutzerkennung
email	E-Mail-Adresse
firstName	Vorname
lastName	Nachname
msisdn	Telefonnummer
company	Firmenname (Arbeitgeber des Kontakts, falls erfasst)
city, state, street, zip	Adressfelder
status	Kontakt-Lebenszyklusstatus (siehe unten). Positive Nachrichtenablauf-Smart-Leads verwenden "1" wie Web-Formular-Leads.
leadSentiment	"positive" oder "negative", wenn eine Nachrichtenablauf-Antwort klassifiziert wurde; sonst ausgelassen
leadCapturedAt	ISO-8601-Zeitpunkt, zu dem der Kontakt ein positiver Smart Lead wurde (fällt auf updatedAt zurück, wenn nicht vorhanden)
tags	Aufgelöste Kontakt-Tags { id, name, systemKind? }[] (einschließlich Auto: Positive Lead / Auto: Negative Lead)
brandId	Markenkennung
operatorId	Unternehmens-/Operator-Kennung
createdAt	ISO-8601-Erstellungszeitstempel
updatedAt	ISO-8601-Zeitstempel der letzten Aktualisierung
lastConversationDate	ISO-8601-Datum des letzten Gesprächs
acceptedCommunication	Ob der Kontakt Kommunikation akzeptiert hat
acceptedPrivacy	Ob der Kontakt Datenschutzbedingungen akzeptiert hat
inviterUser	Wer diesen Kontakt empfohlen hat (Objekt)
rewardFlows	Abläufe, bei denen Belohnungen verdient wurden
promosPresented	Dem Kontakt angezeigte Aktionen
promosRedeemed	Eingelöste Aktionen
answeredSurveyQuestions	Umfrageantworten
usersReferred	Von diesem Kontakt geworbene Nutzer
referralLinks	Details zum Empfehlungslink
visitList	Besuchs-/Sitzungshistorie (Gerät, UTM, Geo usw.)
textFields	In Abläufen erfasste benutzerdefinierte Textfelder

Felder können null sein oder fehlen, wenn sie für diesen Kontakt nicht erfasst wurden.

Kontaktstatus-Werte

Status	Bedeutung
"1"	Lead (einschließlich positiver Nachrichtenablauf-Smart-Leads)
"2"	Kunde
"3"	Verloren
"4"	Konvertiert
null	Wird in Zählungen als Lead behandelt

Verschachtelte Objektstrukturen

inviterUser

{
  "id": 123,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]"
}

rewardFlows / promos

{ "id": "...", "title": "Summer promo" }

referralLinks

{
  "key": "...",
  "campaignId": 1,
  "campaignName": "...",
  "flowVariantId": 1,
  "url": "https://...",
  "share": true
}

visitList — enthält browser, os, deviceType, country, region, city, UTM-Felder (utmSource, utmMedium, utmCampaign usw.), referrer, landingPage, userAgent, ip.

answeredSurveyQuestions — enthält Frage-/Antworttext, Übersetzungen, Belohnungsinformationen und Zeitstempel.

textFields — benutzerdefinierte Ablauf-Felder: flowId, flowName, variantId, variantName, key, value.

Fehlerantworten

Alle Fehler liefern JSON mit einem error-Feld. Einige enthalten ein hint.

HTTP-Status	Bedingung	Beispiel-Body
401	Fehlender token-Header	{ "error": "Missing token header" }
401	Ungültiger/widerrufener Schlüssel oder sk_/pk_-Schlüssel verwendet	{ "error": "Invalid or revoked token", "hint": "You can create a valid token from the Integration Dashboard." }
403	Gültiger Schlüssel, aber kein operatorId-Claim	{ "error": "Unauthorized" }
422	limit > 500	{ "error": "limit must not exceed 500" }
422	Ungültiger sortByField	{ "error": "Invalid sortByField value" }
422	Ungültiger status	{ "error": "Invalid status value" }
404	Falscher Pfad oder Methode	Not Found (Plain Text)

Beispielanfragen

Einfach — bis zu 100 Kontakte abrufen:

curl -s \
  -H "token: YOUR_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact"

25 Kontakte abrufen, sortiert nach letztem Gespräch:

curl -s \
  -H "token: YOUR_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact?limit=25&sortByField=lastConversationDate"

Standard-Leads abrufen (Web-Formular und positive Nachrichtenablauf-Smart-Leads):

curl -s \
  -H "token: YOUR_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact?status=1&sortByField=leadCapturedAt"

Beispiel einer gekürzten Antwort:

{
  "data": [
    {
      "id": "665a1b2c3d4e5f6789012345",
      "email": "[email protected]",
      "firstName": "Alex",
      "lastName": "Smith",
      "msisdn": "+4712345678",
      "status": "2",
      "operatorId": "10",
      "createdAt": "2025-03-15T10:22:00.000Z",
      "lastConversationDate": "2025-06-01T14:30:00.000Z",
      "visitList": [
        {
          "deviceType": "mobile",
          "browser": "Chrome",
          "country": "NO",
          "utmSource": "google"
        }
      ]
    }
  ],
  "leadsCount": 120,
  "customerCount": 45
}

Zapier-Integration

SMOC stellt eine Zapier-App bereit, die denselben Endpunkt verwendet. Typischer Ablauf:

1. Zugriff über den Zapier-Einladungslink erhalten (verlinkt unter Console → Einstellungen → Integrationen → Zapier).
2. API-Schlüssel in der Console generieren.
3. In Zapier: Meine Apps → Eigene Integrationen → Verbindung hinzufügen und den Schlüssel einfügen, wenn nach einem Token gefragt wird.
4. Einen Zap mit dem Trigger SMOC → Neuer Kontakt erstellen.

Der Zapier-Trigger pollt diesen Endpunkt und behandelt zurückgegebene Kontakte als neu, wenn sie erscheinen. Neuer Kontakt basiert auf id. Spät konvertierende Smart-Leads (importierte Interessenten, die später leadCapturedAt erhalten) bekommen jetzt eine stabile {contactId}__sl-ID, sodass der bestehende New Contact Zap einmal ausgelöst werden kann. contactId bleibt die Mongo-ID für CRM-Zuordnung. Dies gilt für jedes Unternehmen; nur Erfassungen ab dem 11.09.2026 werden umgeschrieben (vorübergehend, bis ein dedizierter New Smart Lead-Trigger existiert). Bevorzugen Sie HubSpot Kontakt erstellen oder aktualisieren anhand der E-Mail, um Duplikate zu vermeiden, falls der Interessent bereits synchronisiert wurde. Siehe den Zapier eGuide für eine Schritt-für-Schritt-Anleitung.

Einschränkungen und Designhinweise

• Kundenschlüssel sind schreibgeschützt — mongocontact schreibt nicht. REST v2-Änderungswerkzeuge sind nur für Super-Admins.
• Keine Offset-/Cursor-Paginierung — verwenden Sie limit (max. 500). Um alle Kontakte zu synchronisieren, sortieren Sie konsistent und verfolgen Sie gesehene IDs clientseitig oder nutzen Sie das Polling-Modell von Zapier.
• Automatische Beschränkung — der API-Schlüssel bestimmt das Unternehmen; es gibt keinen Multi-Tenant-Override-Parameter.
• Feldprojektion — es werden nur die oben gelisteten Felder zurückgegeben; interne Datenbankfelder werden entfernt.
• Legacy-Kompatibilität — der Endpunktpfad und das companyUsers.lastConversationDate-Sortieralias existieren zur Rückwärtskompatibilität mit der ursprünglichen API und der Zapier-App.

Verwandt: MCP (KI-Clients)

Der gleiche API-Worker stellt auch MCP unter https://api.smoc.ai/mcp und REST v2 unter POST /api/v2/{toolName} mit erweiterten Kontaktwerkzeugen bereit (contacts_search, contacts_get, contacts_get_stats usw.). Siehe den MCP eGuide und die REST v2-Referenz.

Für einen Produktüberblick aller Integrationswege siehe smoc.ai/integrations.

Schnellreferenz

Element	Wert
Endpunkt	GET /api/company/mongocontact
Auth-Header	token: <api-key>
Content-Type	application/json
Maximale Seitengröße	500
Standard-Seitengröße	100
Unternehmensbezug	Vom API-Schlüssel (operatorId-Claim)
Schlüsselerstellung	Console → Einstellungen → Integrationen → API

Siehe auch

• REST v2 API-Referenz — jeder POST /api/v2/{toolName}-Aufruf
• SMOC mit der REST API verbinden
• Public Contacts API
• MCP für Claude, Cursor und VS Code