Scoutello API
Die Scoutello API ist eine Server-zu-Server-API zur bidirektionalen Synchronisierung der Kontakte, Aufgaben, Protokolle, Verkaufschancen, Projekte, Meilensteine und Veranstaltungen einer Organisation. Außerdem bietet sie schreibgeschützten Zugriff auf den Verlauf ausgehender E-Mails, die Suche nach zuweisbaren Mitgliedern und die Ermittlung von Entitäts-Tags. In dieser Version dienen inkrementelle GET/list-Routen und idempotente Batch-Upserts als Grundlage für die Synchronisierung. Löschvorgänge und Webhooks werden nicht unterstützt.
Die Basis-URL der API lautet:
https://admin.scoutello.com/api/v1
Sie wird außerdem unter Organisationseinstellungen → Developer/API angezeigt. Das OpenAPI-Dokument ist verfügbar unter:
https://admin.scoutello.com/api/v1/openapi.json
Schlüssel erstellen und schützen
Bei modularen Organisationen muss zusätzlich zu den erforderlichen Berechtigungsbereichen des Schlüssels das CRM-Modul aktiv sein. Ein gültiger Schlüssel kann kein fehlendes Modul aktivieren. Wenn kein CRM-Zugriff verfügbar ist, geben Anfragen den HTTP-Status 403 mit dem Fehlercode module_not_active zurück. Eine Person mit Organisationsadministrationsrechten kann CRM unter Abonnement prüfen oder aktivieren; nach der Aktivierung des Zugriffs die Anfrage erneut senden.
Eine Person mit Organisationsadministrationsrechten kann unter Organisationseinstellungen → Developer/API eine Integration und einen API-Schlüssel erstellen. Der vollständige Schlüssel wird nur einmal angezeigt. Vor dem Schließen des Dialogs in einem Secret-Manager speichern; Scoutello kann den vollständigen Schlüssel anschließend nicht erneut anzeigen.
- Für jedes externe System und jede Umgebung eine eigene Integration und einen eigenen Schlüssel verwenden.
- Nur die Berechtigungsbereiche vergeben, die das jeweilige System benötigt.
- Einen Schlüssel niemals in Browser-Code, einer URL, der Versionsverwaltung, Protokollen, Supportnachrichten oder clientseitigem Speicher ablegen.
- Schlüssel regelmäßig rotieren. Bei der Rotation einer aktiven Integration funktioniert der Ersatzschlüssel sofort. Der bisherige Schlüssel bleibt höchstens 15 Minuten gültig, damit das externe System ohne Ausfall wechseln kann. Eine bereits festgelegte frühere Ablaufzeit gilt weiterhin; daher kann der bisherige Schlüssel auch früher ungültig werden.
- Wenn ein Schlüssel möglicherweise offengelegt wurde, die Integration vor der Rotation pausieren. Während der Pause werden alle Schlüssel der Integration vorübergehend abgelehnt. Bei einer Rotation im pausierten Zustand gibt es keine Überschneidung: Der bisherige Schlüssel bleibt deaktiviert, und der Ersatzschlüssel bleibt deaktiviert, bis die Integration fortgesetzt wird.
- Beim Trennen eines externen Systems die gesamte Integration dauerhaft widerrufen. Der Widerruf deaktiviert alle zugehörigen Schlüssel und kann nicht rückgängig gemacht werden.
Den Schlüssel bei jeder authentifizierten Anfrage mitsenden:
Authorization: Bearer YOUR_API_KEY
Die Bearer-Authentifizierung wird bevorzugt. Clients, die Authorization nicht setzen können, dürfen stattdessen x-api-key verwenden. Nicht beide Header senden; Anfragen mit unterschiedlichen Werten in beiden Headern werden abgelehnt.
Die API ist für Backend-Clients vorgesehen und ermöglicht keinen Cross-Origin-Zugriff durch Browser.
Nach der Konfiguration eines Schlüssels GET /whoami verwenden, um die Integration, Organisation, Berechtigungsbereiche und Schlüssellimits zu überprüfen, ohne personenbezogene Daten abzurufen.
Berechtigungsbereiche
| Bereich | Ermöglicht |
|---|---|
contacts.read | Kontakte auflisten und abrufen. Kontakte von Organisationskonten und Mitgliedern mit Zugriffsrechten sind ausgeschlossen. |
contacts.write | Kontakt-Upserts validieren und anwenden. |
tasks.read | Nicht private Aufgaben auflisten und abrufen. |
tasks.write | Aufgaben-Upserts validieren und anwenden. |
protocols.read | Nicht private Protokolle auflisten und abrufen. |
protocols.write | Protokoll-Upserts validieren und anwenden. |
opportunities.read | Verkaufschancen auflisten und abrufen. |
opportunities.write | Verkaufschancen-Upserts validieren und anwenden. |
projects.read | Projekte auflisten und abrufen. |
projects.write | Upserts von Projekten und Beteiligten validieren und anwenden. |
milestones.read | Projektmeilensteine auflisten und abrufen. |
milestones.write | Meilenstein-Upserts validieren und anwenden. |
members.read | Akzeptierte Mitglieder mit ausschließlich der Customer-ID des Mitglieds, der User-ID und dem Anzeigenamen auflisten. |
events.read | Veranstaltungen und zentrale Zeitpläne auflisten und abrufen. |
events.write | Veranstaltungs-Upserts validieren und anwenden. |
mails.read | Verlauf der gesendeten und fehlgeschlagenen ausgehenden E-Mails im Besitz der Organisation lesen. |
mail-drafts.read | Eigenständige E-Mail-Entwürfe dieser Integration zur Genehmigung durch Personen sowie den Zustellstatus lesen. |
mail-drafts.write | E-Mail-Entwürfe zur Genehmigung durch Personen vorbereiten oder überarbeiten; niemals genehmigen oder senden. |
tags.read | Auswählbare Tags für unterstützte Entitätstypen ermitteln. |
Private Aufgaben und Protokolle werden von dieser API niemals zurückgegeben. Bei fehlendem Bereich wird ein Autorisierungsfehler zurückgegeben; dies wird nicht als leeres Ergebnis behandelt.
Ein CRM-Kontakt, der kein Mitglied ist, kann gelesen und referenziert werden, auch wenn er mit einem Scoutello-Login verknüpft ist. Die Antwort enthält ausschließlich die CRM-Felder der Organisation, niemals Identitäts- oder Zugriffsfelder des Users. Kontakte mit einer Rolle, Berechtigungen, Einladung, Akzeptierung oder einem Organisationskontostatus bleiben verborgen. Das Bearbeiten eines mit einem Login verknüpften Kontakts bleibt untersagt (protected_contact), auch wenn ansonsten unveränderte CRM-Felder übermittelt werden. Zum Referenzieren eines vorhandenen lesbaren Kontakts aus einer Aufgabe oder einem Protokoll kann contacts.write dessen externe Verknüpfung ausschließlich mit externalId, scoutelloId und optional externalUpdatedAt herstellen. Spätere Aktualisierungen, die nur die Verknüpfungsmetadaten betreffen, verwenden externalId und optional externalUpdatedAt; scoutelloId nach der Verknüpfung weglassen. Dadurch werden weder der Kontakt noch dessen User geändert. Die Zuordnung akzeptierter Mitglieder verwendet die separate Projektion members.read.
Neue Schlüssel verwenden das Präfix sctl_api_ und beginnen ausschließlich mit contacts.write. Jeder weitere Geltungsbereich erfordert eine ausdrückliche Freigabe, die eine Person mit Organisationsadministrationsrechten beim Erstellen oder Rotieren eines Schlüssels erteilen muss. Bestehende Zugangsdaten behalten ihre aktuellen Geltungsbereiche und bleiben gültig.
Projektverknüpfte Kontakte und E-Mail-Entwürfe
Kontakt-Upserts akzeptieren optionale Paare aus projectScoutelloId / projectExternalId und companyScoutelloId / companyExternalId (je Paar eines auswählen). Kontakt, Unternehmensbeziehung und Projektmitgliedschaft werden pro Element atomar gespeichert. Zum Hinzufügen einer Projektmitgliedschaft ist projects.write erforderlich; ausgelassene Referenzen bewahren andere Beziehungen und Mitgliedschaften. Beim erneuten Abrufen von Kontaktdetails ist projectParticipations enthalten, wenn projects.read gewährt wurde. Vertriebsprojekt-Agents müssen die Projektreferenz ausdrücklich angeben, auch wenn ein bestehender Kontakt wiederverwendet wird.
Eigenständige Entwürfe verwenden das bestehende System zur menschlichen Freigabe, ohne Workflow-Ausführung:
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /mail-drafts | Seitensweise aufgelistete, integrationsverwaltete Entwürfe; optionale Filter projectScoutelloId und status. |
| GET | /mail-drafts/{scoutelloId} | Aktuelle Version, Prüf-Link, Inhaltshash, Freigabe-/Versandstatus und endgültige E-Mail-ID. |
| GET | /mail-drafts/external/{externalId} | Eine stabile externe ID der Integration nachschlagen. |
| POST | /mail-drafts/batch-upsert | Entwurfsvorbereitung validieren oder anwenden. |
Für die Entwurfsvorbereitung sind mail-drafts.write, contacts.read und projects.write erforderlich. Der referenzierte Kontakt wird dem Projekt als teilnehmende Person zugeordnet. Die freigebende Person muss ein akzeptiertes Organisationsmitglied mit Berechtigung zum Bearbeiten von E-Mails sein. Die Absenderauswahl verwendet die bereits zulässigen Organisations- oder persönlichen Absendereinstellungen dieses Mitglieds; beliebige Absenderadressen werden nicht akzeptiert.
{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}
Jedes Validierungsergebnis prüfen, bevor der Vorgang mit mode: "apply" wiederholt wird. Die resultierende ID auslesen, um reviewUrl, draftVersion, contentHash, status, dispatchStatus und mailScoutelloId zu erhalten. expectedVersion: 0 nur zur Erstellung verwenden; für Änderungen die aktuell zurückgegebene Version verwenden. Kontext und freigebende Person sind unveränderlich; geprüfte oder versendete Entwürfe lehnen geänderte Inhalte ab. Identische Wiederholungsversuche geben den ursprünglichen Entwurf zurück.
Entwürfe erscheinen in den E-Mail-Tabs von Projekt und Kontakt sowie in Benachrichtigungen zur Genehmigung im Dashboard. Die API-Vorbereitung versendet keine E-Mail, auch keine Benachrichtigungs-E-Mails; das bestehende Verhalten von Workflow-Benachrichtigungs-E-Mails bleibt unverändert. Die zuständige Person kann Empfangende, Betreff, Nachrichtentext und unterstützte Anhänge bearbeiten, die Version speichern und anschließend Genehmigen und senden. Integrationen können weder Genehmigungen erteilen noch Nachrichten versenden. Eine fehlgeschlagene oder mehrdeutige Zustellung wird niemals blind wiederholt. Beim Konvertieren protokollbasierter Entwürfe die Protokolle beibehalten und auf ihre Ersetzungen verweisen.
MCP-Zugriff
Derselbe Scoutello-API-Schlüssel und dieselben Berechtigungsbereiche können mit dem MCP-Endpunkt für streambares HTTP verwendet werden:
https://admin.scoutello.com/api/v1/mcp
Den MCP-Client für das Senden von Authorization: Bearer YOUR_API_KEY konfigurieren. Die ältere /api/mcp-URL bleibt als Pfad-Kompatibilitätsalias bestehen, neue Clients sollten jedoch den versionierten Endpunkt verwenden. Frühere sctl_mcp_-Anmeldedaten werden nicht akzeptiert; diese durch einen Scoutello-API-Integrationsschlüssel ersetzen.
MCP-Tools sind direkt dem REST-Vertrag zugeordnet und verwenden dieselben Laufzeitschemas, Mandantenprüfungen, Integrationslebenszyklen, Ratenbegrenzungen und Servicemethoden. Beispielsweise entsprechen contacts_list, contacts_get, contacts_get_by_external_id und contacts_batch_upsert den vier Kontaktrouten. Dasselbe Muster gilt für Aufgaben, Protokolle, Verkaufschancen, Projekte, Meilensteine und Veranstaltungen. Für E-Mails werden mails_list und mails_get bereitgestellt, für Mitglieder members_list und für Tags tags_list.
Der Server stellt nur Tools bereit, die durch die Berechtigungsbereiche des aktuellen Schlüssels zulässig sind. Ein Schlüssel mit contacts.read kann die Lesewerkzeuge für Kontakte ermitteln, nicht jedoch contacts_batch_upsert. Ein Schlüssel mit contacts.write erhält das Tool für Batch-Upserts, nicht jedoch die Lesewerkzeuge. whoami ist immer verfügbar. Schreibtools haben dieselben unmittelbaren Auswirkungen wie ihre REST-Entsprechungen. mode: "validate" verwenden, wenn ein Aufrufer einen Batch prüfen soll, ohne ihn anzuwenden.
MCP arbeitet ebenfalls von Server zu Server und ermöglicht keinen Cross-Origin-Zugriff durch Browser. Für den JSON-RPC-Transport ist eine eigene URL erforderlich. Daher kann MCP keine einzelne REST-Ressourcen-URL gemeinsam nutzen, obwohl Authentifizierung und Datenverhalten identisch sind.
Eine vollständige Anleitung zur Clientkonfiguration, Überprüfung, Tool-Zuordnung und Fehlerbehebung enthält der Leitfaden zur MCP-Integration.
Datensätze lesen
Kontakte, Aufgaben, Protokolle, Verkaufschancen, Projekte, Meilensteine und Veranstaltungen verwenden dieselben Leserouten:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
contacts durch tasks, protocols, opportunities, projects, milestones oder events für die anderen Synchronisierungsressourcen ersetzen. externalId erscheint in einem Lese-DTO, wenn der Datensatz mit dieser Integration verknüpft wurde.
Eine Listenantwort hat diesen Envelope:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
limit muss zwischen 1 und 100 liegen. Die Ergebnisse werden nach dem effektiven Zeitpunkt geordnet, zu dem sich ihre öffentliche API-Darstellung geändert hat, und anschließend nach der Scoutello-ID. Dieser effektive Zeitpunkt kann nach dem zurückgegebenen Entitätsfeld updatedAt liegen, wenn sich Metadaten zur Integrationsverknüpfung geändert haben. Cursor sind undurchsichtig: unverändert speichern und übermitteln und aus ihrem Inhalt keine Bedeutung ableiten.
Die erste Antwort legt snapshotAt für diesen Durchlauf fest. nextCursor so lange folgen, bis hasMore den Wert „false“ hat, bevor ein weiterer inkrementeller Lesevorgang gestartet wird. Dadurch wird verhindert, dass sich während der Seitennavigation ändernde Datensätze den aktuellen Durchlauf instabil machen.
Für die inkrementelle Synchronisierung jede Cursor-Seite verarbeiten und anschließend den snapshotAt dieses Durchlaufs als Zeitstempel für den höchsten verarbeiteten Stand speichern. Beim nächsten Durchlauf als ISO-8601-Wert updatedSince übergeben. Die Untergrenze ist inklusiv. Daher kann eine Wiederholung eines abgeschlossenen Snapshots Datensätze an der Grenze zurückgeben, sie jedoch nicht überspringen.
Eine Einzelantwort hat diesen Envelope:
{
"data": {},
"requestId": "request-id"
}
Antworten für einzelne Kontakte enthalten außerdem ein Array relations. Jede Beziehung enthält ihre Scoutello-Beziehungs-ID, den Erstellungszeitpunkt, den Typ, Notizen sowie die Kontaktverweise connectedFrom und connectedTo. Kontaktverweise enthalten die Scoutello-ID und, sofern vorhanden, die externe ID dieser Integration. Kontakte, die aufgrund der Datenschutzgrenze für den Organisationszugriff von der API ausgeschlossen sind, werden über Beziehungen nicht offengelegt.
Die Antwort der Kontaktliste bleibt kompakt und enthält keine Beziehungen. Für Beziehungsdetails eine der Routen für einzelne Kontakte verwenden.
Arbeitsfilter und Cursor-Gültigkeitsbereich
Kontaktlisten akzeptieren search, type (person, company, supplier, other), status und tagIds. Die Suche wird gekürzt, ist nicht groß-/kleinschreibungssensitiv und auf 200 Zeichen bzw. 10 durch Leerzeichen getrennte Tokens begrenzt. Jedes Token muss in mindestens einem der Felder firstName, lastName oder companyName vorkommen, einschließlich früherer Unternehmensnamen, die in lastName gespeichert sind. Zeichen wie % und _ werden wörtlich abgeglichen. Tags verwenden eine Any-of-Übereinstimmung mit 1–50 IDs. Alle angegebenen Filter werden mit AND verknüpft. REST codiert Tag-IDs als wiederholte Parameter; MCP übergibt ein Array:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
Kontakt-Cursor sind an die Organisation, die Integration und jeden Filter gebunden. Filter auf jeder Seite beibehalten; eine Änderung eines Filters führt zur Ablehnung des Cursors. Reihenfolge und Duplikate von Tags sowie Reihenfolge, Groß-/Kleinschreibung und Leerraum der Such-Tokens ändern den effektiven Filter nicht.
Arbeitslistenrouten akzeptieren die folgenden zusätzlichen Filter; andere Kombinationen aus Ressourcen und Feldern werden abgelehnt:
| Ressource | Filter |
|---|---|
| Aufgaben | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| Protokolle | projectScoutelloId, milestoneScoutelloId, status (draft oder final) |
| Verkaufschancen | projectScoutelloId, stage, ownerScoutelloUserId |
| Projekte | status, assignedContactScoutelloId |
| Meilensteine | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
dueBefore ist exklusiv; dueAfter ist inklusiv. Verglichen werden das Fälligkeitsdatum der Aufgabe oder das Enddatum des Meilensteins; Datensätze ohne dieses Datum stimmen nicht überein. Zeitzonenbezogene ISO-Datums-/Zeitangaben übergeben. Alle Filter werden vor der Paginierung angewendet. Einen Cursor mit exakt denselben Filtern, einschließlich updatedSince, sowie derselben Organisation/Integration fortsetzen. Die Seitengröße darf geändert werden. Alte Cursor ohne Bereichszuordnung müssen nach dieser Veröffentlichung ab dem gespeicherten Zeitstempel der höchsten bisher verarbeiteten Änderung neu gestartet werden.
Projekte, Meilensteine, Zuweisungen und Notizen
GET /members (MCP members_list) verwendet die Standardpaginierung und erfordert members.read. Es gibt scoutelloId (Customer-ID des Mitglieds), scoutelloUserId (User-ID) und displayName zurück. Angezeigt werden nur akzeptierte Organisationsmitglieder mit einer Rolle; die Abfrage gibt weder E-Mail-Adressen noch Berechtigungen preis.
Aufgaben akzeptieren assignedScoutelloUserIds; für Verkaufschancen wird ownerScoutelloUserId verwendet. Projekte und Meilensteine verwenden assignedContacts: [{"scoutelloId":"member-customer-id"}]. Für Zuweisungen sind akzeptierte Mitglieder der Organisation erforderlich, der die Zugangsdaten zugeordnet sind. Nicht angegebene Zuweisungen bleiben unverändert; [] entfernt sie. Importe von Projekten, Meilensteinen, Aufgaben und Protokollen erfolgen ohne Benachrichtigungen: Es werden weder Zuweisungsbenachrichtigungen noch andere Mitteilungen gesendet.
Bei Veranstaltungen unterstützt assignedContacts lesbare CRM-Kontakte und akzeptierte Mitglieder, die anhand der Customer-ID des Mitglieds angegeben werden. Akzeptierte Mitglieder stehen nicht als gewöhnliche CRM-Kontaktverweise oder Ziele externer Links zur Verfügung; für die Teamverantwortung das Mitglieder-Zuweisungsfeld verwenden.
Meilensteine mit einem name sowie entweder projectScoutelloId oder projectExternalId erstellen. Sie unterstützen description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (Standardwert 0) und assignedContacts. Das Enddatum darf nicht vor dem Startdatum liegen. Jeder Meilenstein verfügt über einen stabilen externen Link im Gültigkeitsbereich der Integration. Das zugehörige Projekt kann nicht über die API geändert werden. Beim Erstellen und Aktualisieren werden Name und Beschreibung in die Sprache der Organisation lokalisiert.
Aufgaben und Protokolle akzeptieren Referenzen auf Projekte, Meilensteine und Verkaufschancen als <entity>ScoutelloId oder <entity>ExternalId, beispielsweise milestoneExternalId. Pro Beziehung darf nur eine Schreibweise verwendet werden, auch beim Aufheben der Zuordnung mit null. Alle Beziehungen müssen zur Organisation des Zugangsdatenobjekts gehören. Eine Referenz ausschließlich auf einen Meilenstein leitet das Projekt daraus ab. Ein widersprüchliches Projekt oder das explizite Aufheben der Projektzuordnung bei gleichzeitig beibehaltenem Meilenstein wird abgelehnt. Eine verknüpfte Verkaufschance mit einem Projekt muss mit dem Projekt der Arbeit übereinstimmen. Nicht angegebene Beziehungen behalten ihre aktuellen Werte bei; ein explizites null hebt eine Beziehung auf, sofern der verbleibende Kontext gültig ist. Lesevorgänge geben beide ID-Schreibweisen und Aufgabenzuweisungen zurück.
Aufgabenplanung und Workflows
Der status einer Aufgabe ist der unveränderliche Schlüssel eines Status im effektiven Workflow der Aufgabe und keine feste Aufzählung. Die verfügbaren Workflows der Organisation und des Projekts mit GET /task-workflows unter Verwendung des Bereichs tasks.read auslesen. Jeder Status enthält seinen Schlüssel, seine Bezeichnung, seinen Lebenszyklus type (backlog, unstarted, started, completed oder cancelled), seine Farbe, seine Reihenfolge, ein Standardflag und seinen Archivierungsstatus. Bei Projektelementen wird angegeben, ob der Organisations-Workflow übernommen wird. Die Workflow-Konfiguration wird weiterhin über das Dashboard verwaltet.
Aufgaben akzeptieren nullable priority (low, medium, high oder urgent) und estimatedEffortMinutes sowie nullable startDate und dueDate. Lesevorgänge für Aufgaben enthalten statusType in denormalisierter Form, die übergeordnete Referenz, kompakte Unteraufgabenreferenzen sowie blockedBy- und blocks-Referenzen.
Eine einstufige Unteraufgabe mit entweder parentTaskScoutelloId oder parentTaskExternalId erstellen oder aktualisieren; null stuft sie zu einer Aufgabe der obersten Ebene hoch. Abhängigkeiten verwenden Arrays mit Referenzen auf { "scoutelloId": "..." } oder { "externalId": "..." } in blockedBy und blocks. Ausgelassene Beziehungsfelder bleiben unverändert, während ein leeres Abhängigkeits-Array die jeweilige Richtung löscht. Die API lehnt verschachtelte Unteraufgaben, Abhängigkeiten zwischen übergeordneter Aufgabe und Unteraufgabe, organisationsübergreifende Abhängigkeiten, Duplikate, Selbstreferenzen sowie direkte oder transitive Zyklen ab.
Filter für Aufgabenlisten akzeptieren einen exakten Workflow status, einen Lebenszyklus statusType, priority, parentState (top_level, subtask oder parent) sowie blockedState (blocked, blocking oder unblocked).
Protokolle akzeptieren zusätzlich status: "draft" | "final" (neue Datensätze verwenden standardmäßig final). Für ein neues Protokoll sind type, date und entweder ein Kontakt oder ein gültiger Projekt-/Meilenstein-Kontext erforderlich. contactExternalId: null hebt die Kontaktzuordnung nur auf, wenn der Projekt-/Meilenstein-Kontext bestehen bleibt. So können interne Projektnotizen erstellt und gelesen werden, ohne einen Kontakt zu erfinden. Draft/final beschreibt den Status der Notiz und versendet niemals eine Nachricht. Private Aufgaben und Protokolle bleiben nicht zugänglich.
Projektbeteiligte
Das Projektfeld participants enthält additive Upserts, die über eine contact-Referenz identifiziert werden, zum Beispiel:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
Beteiligte beschreiben Interessierte oder Kontakte, die mit einem Projekt verbunden sind; für verantwortliche Teammitglieder werden Zuweisungen verwendet. Ausgelassene Beteiligte, ein leeres Array und ausgelassene Beteiligtenfelder bewahren die vorhandenen Daten. null löscht role, notes oder groupScoutelloId. Doppelte aufgelöste Kontakte innerhalb einer Nutzlast werden abgelehnt. Gruppen müssen bereits zum ausgewählten Projekt gehören; Lesevorgänge enthalten participantGroups (ID/Name) sowie Beteiligten-IDs, Kontakte, Rolle, Notizen und Gruppen-ID. Das Entfernen von Beteiligten und das Erstellen von Gruppen ist derzeit im Dashboard verfügbar.
Datensätze stapelweise aktualisieren oder erstellen
Mit der Batch-Route der Ressource bis zu 100 Datensätze schreiben:
POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}
Bei Aufgaben-Batches werden die Aufgabendatensätze aufgelöst, bevor übergeordnete Aufgaben und Abhängigkeiten angewendet werden. Diese zweistufige Verarbeitung ermöglicht es, dass eine übergeordnete Aufgabe, eine blockierende oder eine blockierte Aufgabe auf eine andere Aufgabe verweisen kann, die im selben Batch anhand ihrer externen ID erstellt wurde, unabhängig von der Reihenfolge der Datensätze.
Für die Felder und Validierungsregeln jeder Ressource das OpenAPI-Dokument verwenden. Jeder Datensatz muss über ein stabiles externalId mit einer Länge zwischen 1 und 200 Zeichen verfügen. Dieses als undurchsichtigen technischen Bezeichner behandeln: Keine E-Mail-Adresse, keinen Namen, kein API-Geheimnis und keine anderen personenbezogenen Daten verwenden. externalUpdatedAt ist optional, wird jedoch dringend empfohlen, wenn das Quellsystem einen zuverlässigen Änderungszeitpunkt bereitstellt.
Der Anfragetext ist auf 1 MiB begrenzt. mode verwendet standardmäßig apply:
applyvalidiert akzeptierte Datensätze und schreibt sie.validateführt dieselbe Validierung und Zuordnung ohne Schreibvorgang durch und gibt Ergebnisse in Form vonwould_*zurück.
Für Kontaktimporte kann matchByEmail in der Anfrage auf true gesetzt werden. Standardmäßig wird false verwendet; die externe ID bildet die sicherere Identitätsgrenze.
Ausgelassene Felder behalten ihren aktuellen Wert. Ein explizites null leert ein nullable Feld. Ein übergebenes leeres Array für Zuordnungen oder Tags hebt die entsprechende Beziehung auf. Projekt-participants werden additiv per Upsert verarbeitet: Ein leeres Array lässt die Projektliste unverändert. Beim Schreiben von Tags für Kontakte, Aufgaben, Verkaufschancen und Veranstaltungen werden Scoutello-Tag-IDs verwendet. Externe IDs von Beziehungen werden nur über Links aufgelöst, die zur aktuellen Integration gehören. Für die Zuständigkeit oder Verantwortung verwendete Scoutello-Benutzer-IDs müssen akzeptierte Mitglieder der aktuellen Organisation identifizieren.
Zum Erstellen von Verkaufschancen ist ein Konto oder Kontakt erforderlich; für verlorene Verkaufschancen muss ein Verlustgrund angegeben werden. Geldbeträge werden als ganzzahlige Cent-Beträge verwendet. Namen und Beschreibungen von Projekten und Veranstaltungen werden in der konfigurierten Sprache der Organisation gelesen und geschrieben. Beim Schreiben von Veranstaltungen können explizite Daten sowie tägliche, wöchentliche oder monatliche Wiederholungen mit Ausnahmen angegeben werden. Veröffentlichte Sichtbarkeitsstufen unterliegen weiterhin den rechtlichen Freigabebedingungen von Scoutello. Die API bietet keinen Zugriff auf Ticketing, Teilnehmende, Medien, Vorlagen, Newsletter, Kooperationen oder andere erweiterte Funktionen der Veranstaltungsverwaltung.
Tags ermitteln
Vor der Übergabe von tagIds den Tags-Endpunkt verwenden:
GET /tags?entity=events&type=category
entity ist erforderlich und akzeptiert contacts, tasks, opportunities oder events. Der Wert wird der entsprechenden gespeicherten Tag-Relevanz zugeordnet. type ist optional und akzeptiert category oder attribute. Auswählbare Kategorien können der Organisation gehören oder global sein; auswählbare Attribute stammen aus dem kuratierten globalen Attributsatz von Scoutello. Die Ergebnisse enthalten scoutelloId, den in die Organisationssprache lokalisierten Namen, type und relevancy. Organisationsübergreifende, mit der falschen Relevanz versehene oder nicht auswählbare Tag-IDs führen zur Ablehnung des betroffenen Batch-Elements.
Verlauf ausgehender E-Mails lesen
Der Mailverlauf ist schreibgeschützt:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
Es werden nur organisationsbezogene Mails mit dem Status sent oder failed zurückgegeben. Die Antworten enthalten gängige gespeicherte Header und den Nachrichtentext, BCC, Status und Zeitstempel, Verweise auf Projekte/Events/Newsletter, IDs und Typen von Anhängen sowie aggregierte Statistiken zur Zustellung, Öffnung, Klickrate, Unzustellbarkeit, Beschwerden und Ablehnung auf Empfangsseite. Entwürfe, Mails in der Warteschlange oder geplante Mails, Datensätze pro empfangender Person, gerenderte Snapshots, rohe Provider-Fehler und URLs zum Herunterladen von Anhängen werden nie offengelegt. Eine spätere Aktualisierung der Zustellung an empfangende Personen setzt den effektiven Synchronisierungszeitstempel der Mail weiter, sodass die Mail bei inkrementellen Lesevorgängen erneut erscheint. Es gibt keine Routen zum Schreiben von Mails.
Ein Anwendungsergebnis kann created, updated, linked, unchanged, stale_ignored oder rejected sein. Für die Validierung werden would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale oder rejected verwendet. Eine gültige Batch-Anfrage gibt HTTP 200 zurück, auch wenn einzelne Datensätze abgelehnt werden. Daher immer jedes Element und die Zusammenfassung der Antwort prüfen. Die Antwort requestId aufbewahren, wenn der Scoutello-Support einen Fehler untersuchen soll.
Zeitstempel und Konflikte
Wenn externalUpdatedAt vorhanden ist, verwendet Scoutello diesen Wert, um veraltete Änderungen abzulehnen, ohne den übrigen Batch fehlschlagen zu lassen. Ein Ergebnis mit stale_ignored ist für diese ältere Nutzlast endgültig. Vor dem Senden einer neueren Version den aktuellen Datensatz abrufen.
Zeitstempel als UTC-Werte im ISO-8601-Format behandeln. Die ursprüngliche Genauigkeit beibehalten und nicht den Zeitpunkt eines Synchronisierungsjobs anstelle des Änderungszeitpunkts des Quelldatensatzes verwenden.
Idempotenz
Die Idempotenzgrenze liegt bei der Integration und externalId. Scoutello vergleicht einen kanonischen Nutzlast-Hash und den optionalen Wert externalUpdatedAt. Dadurch werden beim erneuten Versuch für denselben Datensatz keine Duplikate erstellt, und es kann unchanged zurückgegeben werden.
Mit externalUpdatedAt gilt derselbe Zeitstempel mit derselben Nutzlast als unchanged, ein älterer Zeitstempel als stale_ignored und derselbe Zeitstempel mit einer anderen Nutzlast als Versionskonflikt. Bei einem Link, der noch keinen Zeitstempel akzeptiert hat, bleibt dieselbe Nutzlast ohne Zeitstempel unchanged, während eine geänderte Nutzlast in der Reihenfolge ihres Eingangs angewendet wird. Nachdem ein Link einen Zeitstempel akzeptiert hat, wird eine geänderte Nutzlast ohne externalUpdatedAt als Versionskonflikt abgelehnt, damit nicht versionierte Daten den versionierten Status überschreiben können. Deshalb werden Änderungszeitstempel aus der Quelle dringend empfohlen.
Auditprotokoll
Akzeptierte API-Erstellungs-, Aktualisierungs- und Nur-Verknüpfungs-Synchronisierungsaktionen erscheinen in den Scoutello-Änderungsprotokollen mit Public API als Quelle und werden der verantwortlichen Integration zugeordnet. Zusammenfassungen der Betriebsläufe enthalten Request-IDs und aggregierte Ergebniszahlen zur Fehlerbehebung. Datensatzinhalte oder API-Schlüssel werden nicht gespeichert.
Fehler und Wiederholungen
Fehler auf Request-Ebene verwenden dieses Format:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
HTTP-429- und vorübergehende 5xx-Antworten mit exponentiellem Backoff und Jitter wiederholen. Retry-After beachten, sofern vorhanden. Netzwerkfehler können auftreten, nachdem Scoutello eine Anfrage akzeptiert hat. Das erneute Senden desselben Batches ist sicher, da jeder Datensatz anhand der externen ID und der kanonischen Nutzdaten idempotent ist. Authentifizierungs-, Autorisierungs-, Validierungs- und Versionskonfliktfehler sowie einzelne rejected-Ergebnisse nicht automatisch wiederholen, ohne die Anfrage zu ändern.
Empfohlener Zwei-Wege-Synchronisierungsablauf
/whoamiwährend der Einrichtung aufrufen und die erwartete Organisation sowie die Berechtigungsbereiche überprüfen.- Jede seit dem letzten abgeschlossenen High-Water-Mark geänderte Seite lesen und die Änderungen idempotent auf das externe System anwenden.
- Externe Änderungen an
/batch-upsertsenden und dabei stabile externe IDs sowie Zeitstempel der Änderungen aus der Quelle verwenden. - Prüfpunkte erst speichern, nachdem alle Seiten und Einzelergebnisse verarbeitet wurden.
- Konflikte gemäß den Besitzregeln des Quellsystems auflösen; Löschungen nicht durch das Senden leerer Datensätze nachbilden.
Scoutello stellt in dieser ersten Version bewusst keine öffentliche Löschroute bereit. Lösch- oder Archivierungsrichtlinien außerhalb der API handhaben, bis eine dokumentierte Lebenszyklusoperation eingeführt wird.
Social-Media-Beiträge zur menschlichen Prüfung
Die Social API bereitet Beiträge für eine namentlich benannte prüfende Person vor. Sie kann die Beiträge weder genehmigen noch veröffentlichen. REST und MCP verwenden dieselben Berechtigungsbereiche und denselben Dienst.
| Berechtigungsbereich | Endpunkte unter /api/v1 |
|---|---|
social-channels.read | GET /social-channels |
social-posts.read | GET /social-posts, GET /social-posts/{scoutelloId} |
social-post-drafts.read | GET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId} |
social-post-drafts.write | POST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize |
Neue Berechtigungsbereiche müssen ausdrücklich gewährt werden. Vorhandene Zugangsdaten erhalten keinen zusätzlichen Zugriff. members.read verwenden, um die Benutzer-IDs der Mitglieder abzurufen, und eine prüfende Person mit Veröffentlichungsberechtigung auswählen (newsletter.edit). Für Entwürfe ist weder ein CRM-Kontakt noch ein Projekt erforderlich.
{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}
Zum Veröffentlichen nach der Freigabe publishMode: "now" und scheduledAt: null verwenden. Jede Kanalvariante enthält den vollständigen Text, die Einstellungen und die geordneten Medien-IDs.
Die Kanalerkennung liefert unterstützte Formate, Limits und Einstellungen. Derzeit werden LinkedIn-Profile/-Seiten, Facebook, Instagram und Threads unterstützt. Für Instagram sind Medien erforderlich. Eine Variante akzeptiert bis zu zehn Bilder oder Videos.
Stapel akzeptieren bis zu 100 eindeutige externe IDs innerhalb des bestehenden Anfrage-Limits von 1 MiB. mode: "validate" prüft Referenzen und Versionen, ohne Entwürfe zu speichern, Assets hochzuladen, Benachrichtigungen zu erstellen oder Aufgaben in die Warteschlange einzureihen. Die Ergebnisse der Anwendung enthalten IDs, Prüflinks, Versionen und Ergebnisse für jeden Datensatz. Teilfehler führen nicht zum Zurücksetzen erfolgreicher Datensätze. Bei einem Fehler der Benachrichtigung wird eine Warnung mit der gespeicherten Prüf-URL zurückgegeben.
Vor der Überarbeitung eines ausstehenden Entwurfs die aktuelle Version von draftVersion abrufen. Identische Wiederholungsversuche sind idempotent und bewahren spätere manuelle Änderungen. Prüfende Personen können nicht direkt geändert werden. Nach der Freigabe oder Ablehnung eine neue externe ID für einen weiteren Vorschlag verwenden. Das Lesen von Entwürfen ist auf die aufrufende Integration beschränkt. Der Veröffentlichungsverlauf umfasst alle in der Organisation gespeicherten, von Scoutello erstellten Kampagnen, einschließlich Beiträgen aus dem Dashboard, aus Skripten und aus älteren Scoutello-Versionen. Der Verlauf externer Kanäle wird nicht importiert.
Listen verwenden die standardmäßigen Parameter limit, cursor und updatedSince. Beiträge und Entwürfe akzeptieren außerdem channelId, status, after, before und search. Alle Filter auf nachfolgenden Cursor-Seiten beibehalten. Datumsfilter beziehen sich auf den Veröffentlichungszeitpunkt, bei unmittelbar ausstehenden Entwürfen auf den Erstellungszeitpunkt. Der Entwurfsfilter status filtert nach dem Freigabestatus. status für Beiträge stimmt mit dem Auslieferungsstatus einer Kampagne oder eines Kanals überein. Die Lesevorgänge enthalten den zuletzt bekannten Auslieferungsstatus, Fehler pro Kanal, öffentliche Links und Zeitstempel des Abgleichs. Inkrementelle Lesevorgänge von Entwürfen berücksichtigen außerdem Änderungen an der Kampagnenauslieferung.
Medien hochladen
POST /social-media/uploadsmitclientUploadId,filename,contentType,sizein Bytes und dem kleingeschriebenen Hexadezimalwertsha256der ursprünglichen Bytes aufrufen. Unterstützte Typen sind PNG, JPEG, WebP, MP4, WebM, QuickTime und M4V. Die maximale Uploadgröße beträgt 500 MiB.- Die ursprünglichen Bytes per HTTP
PUTan die zurückgegebeneupload.urlsenden und dabei deren Header verwenden. Upload-URLs laufen nach 15 Minuten ab. Für Wiederholungsversuche derselben DateiclientUploadIdwiederverwenden. Abgelaufene Sitzungen oder andere Dateien erfordern eine neue ID. POST /social-media/uploads/{assetId}/finalizemit einem JSON-Body aus{}aufrufen. Bei der Finalisierung werden Größe, Typ, Signatur und Prüfsumme geprüft, eine private Kopie eingefroren und die Asset-ID fürmediaIdszurückgegeben. Eine wiederholte Finalisierung ist sicher möglich.
Die Upload-Berechtigung ist an die Organisation und die Integration gebunden. Entwürfe können finalisierte Assets aus ihrer Organisation referenzieren. Vorschau-URLs sind temporär. Zum Aktualisieren erneut den Entwurf abrufen. Für finalisierte Objekte werden niemals Upload-URLs ausgestellt.
Manuelle Prüfung und Veröffentlichung
Die prüfende Person erhält eine Dashboard-Benachrichtigung und kann den Beitrag über Postings oder die zugehörige Prüf-URL öffnen. Durch Bearbeiten wird eine weitere unveränderliche Version erstellt. Die Genehmigung verwendet die angezeigte Version und den Inhalts-Hash, prüft die Mitgliedschaft, Kanäle und Assets erneut und erstellt atomar eine dauerhafte Kampagne. Ist der vorgeschlagene Zeitpunkt bereits verstrichen, muss die prüfende Person einen ausdrücklich neuen Zeitpunkt speichern oder die Veröffentlichung bei Genehmigung auswählen.
Bei Wiederholungsversuchen in der Warteschlange werden die Kampagne und ihre Plattformbelege wiederverwendet. Genehmigte Kampagnen können nicht direkt bearbeitet werden. Durch das Abbrechen über das Dashboard bleiben der Genehmigungsverlauf und die Medien erhalten. Ein Abbruch kann keine aktive Veröffentlichung unterbrechen. Den Entwurf oder die Kampagne abfragen, um zwischen der Genehmigung und der tatsächlichen Veröffentlichung auf der Plattform zu unterscheiden.