API-Referenz: Soulclick

Mit der REST-API liest du Spenden, Kontakte und Newsletter-Anmeldungen aus Soulclick aus und änderst die Stammdaten von Kontakten, zum Beispiel für ein CRM, ein Reporting-Tool oder eigene Auswertungen. Für selbst gebaute Spenden-Teaser liefert sie zudem die öffentliche Spenden-Konfiguration eines Kampagnen-Links.

Endpunkte

Alle Endpunkte liegen unter https://<deine-instanz>/api/<version>/. <version> steht für v1, v2 oder v2.1, siehe Versionierung.

Methode	Endpunkt	Inhalt	Berechtigung
`GET`	`/api/<version>/crm/donations/`	Spenden in einem Zeitraum	`customers:read`
`GET`	`/api/<version>/crm/contact/donations/`	Alle Spenden eines Kontakts	`customers:read`
`GET`	`/api/<version>/crm/contacts/`	Kontakte mit Anzahl und Summe ihrer Spenden	`customers:read`
`GET`	`/api/<version>/crm/contacts/<contact_id>/`	Stammdaten eines Kontakts	`customers:read`
`PATCH`	`/api/<version>/crm/contacts/<contact_id>/`	Stammdaten eines Kontakts ändern	`customers:read` und `customers:write`
`GET`	`/api/<version>/crm/newsletter-subscriptions/`	Newsletter-Anmeldungen	`newsletter:read`
`GET`	`/api/<version>/campaign-links/<id>/config/`	Spenden-Konfiguration eines Kampagnen-Links	öffentlich

Alle Parameter, Felder und Beispiel-Antworten findest du in der interaktiven API-Referenz.

Authentifizierung

Jede Anfrage an einen CRM-Endpunkt braucht eine dieser Anmeldungen:

Methode	Header	Geeignet für
API-Token (empfohlen)	`Authorization: Bearer sct_…`	Integrationen: eigene Berechtigungen, Ablaufdatum, kein Passwort eines Admin-Kontos
JWT	`Authorization: Bearer <access>`	Bestehende Integrationen mit einem Admin-Konto
Basic Auth	`Authorization: Basic <base64(benutzername:passwort)>`	Bestehende Integrationen mit einem Admin-Konto, die kein JWT umsetzen können

API-Token

Einen API-Token erstellst du im Admin unter Grundeinstellungen → Zugriff & Berechtigungen → API-Zugriff, siehe API-Zugriff. Er hat nur die Berechtigungen, die du ihm gibst. Welche ein Endpunkt braucht, steht in der Tabelle oben.

JWT

Sende POST /authentication/create mit username und password eines Admin-Kontos. Die Antwort enthält einen access- und einen refresh-Token.
Schicke den access-Token bei jeder Anfrage im Header Authorization: Bearer <access> mit. Er gilt 5 Minuten.
Hol dir mit POST /authentication/refresh und dem refresh-Token einen neuen access-Token. Der refresh-Token gilt einen Tag. Jede Erneuerung liefert auch einen neuen refresh-Token, der alte wird ungültig.
POST /authentication/verify prüft einen Token, POST /authentication/logout macht den refresh-Token ungültig.

JWT und Basic Auth funktionieren nur mit einem Admin-Konto (Mitarbeiterstatus) und geben der Integration dessen Zugangsdaten. Für neue Integrationen nimmst du deshalb einen API-Token.

Fehler

Status	Bedeutung
`400`	Ein Parameter oder Feld fehlt oder ist ungültig. Die Antwort nennt, was nicht stimmt
`401`	Keine oder eine ungültige Anmeldung, oder der API-Token ist abgelaufen oder widerrufen
`403`	Dem API-Token fehlt die Berechtigung, oder das Konto ist kein Admin-Konto
`404`	Den angefragten Kontakt gibt es nicht
`429`	Zu viele Anfragen mit demselben API-Token. Warte kurz und versuche es erneut

Die wichtigsten Parameter

Endpunkt	Parameter
`/crm/donations/`	`dateFrom` und `dateTo` im Format `MM-TT-JJJJ`, z. B. `10-31-2026`. `environment`: `PRODUCTION` für echte Spenden, `TEST` für Testspenden. `paid_only=True` für nur bezahlte Spenden. `email` für die Spenden einer Adresse (exakt). `limit` begrenzt die Anzahl, `0` liefert alle
`/crm/contact/donations/`	`contact_id` oder `email` des Kontakts, optional `environment`
`/crm/contacts/`	`search` (Name oder E-Mail, Teiltreffer), optional `environment`, dazu `limit` (Standard `50`) und `offset` zum Blättern. Die Antwort enthält `count`, `next` und `previous`
`/crm/contacts/<contact_id>/`	`PATCH` mit den Feldern, die sich ändern sollen, als JSON. `contact_id` und `language` lassen sich nicht ändern. Ein Kontakt vom Typ `Geschäft` braucht eine `company`
`/crm/newsletter-subscriptions/`	`search` (Name oder E-Mail, Teiltreffer), `opt_in` (`true` nur bestätigte, `false` nur unbestätigte, ohne Angabe beide), dazu `limit` (Standard `50`) und `offset`. Die Antwort enthält `count`, `next` und `previous`

Achtung: Ohne environment liefert /crm/donations/ nur Testspenden. Für echte Spenden setzt du environment=PRODUCTION.

Spenden-Konfiguration eines Kampagnen-Links

GET /api/<version>/campaign-links/<id>/config/ braucht keine Anmeldung und lässt sich von jeder Website abrufen (CORS). Die Antwort enthält Spendenart, Währung, Beträge und Intervalle, Zahlungsmethoden und Checkout-Links des Kampagnen-Links, damit du einen eigenen Spenden-Teaser bauen kannst. Ein unbekannter oder nicht aktiver Kampagnen-Link antwortet mit 403 und {"error": "not_found"}.

Versionierung

Die Version steht im Pfad. Jede Version bleibt verfügbar und antwortet weiterhin so, wie du sie integriert hast: Ein später ergänztes Feld kommt in einer älteren Version nicht dazu.

Version	Root	Enthält
`v1`	`/api/v1/`	Die bisherige Payload, ebenso unter `/crm-api/`
`v2`	`/api/v2/`	Zusätzlich `custom_fields`: die Antworten der Kontaktperson auf die eigenen Felder des Spendenformulars
`v2.1`	`/api/v2.1/`	Zusätzlich `checkout` an jedem Eintrag von `/crm/donations/`, mit Nummer, Gesamtbetrag und Währung des Multi-Checkouts, und `positions` an jeder Spende eines Kontakts, mit Betrag, Kampagne, Spendenzweck und Zahlungsart jeder Position. Jeder Betrag ist, was bezahlt wurde, inklusive der Gebühren, die die spendende Person übernommen hat, in der Währung der Spende. Zeitangaben stehen in UTC mit `Z`

Ab v2.1 ist ein Multi-Checkout bei den Spenden eines Kontakts ein einziger Eintrag mit dem Gesamtbetrag, und die Kontaktliste zählt ihn als eine Spende. Vor v2.1 erscheint jede Position als eigene Spende.

Ein Wechsel der Version bedeutet nur einen anderen Root: Endpunkte, Parameter und Anmeldung bleiben gleich. Neue optionale Parameter und neue Endpunkte kommen jederzeit dazu, ohne dass sich die Version ändert. Eine Integration muss unbekannte Felder deshalb ignorieren.

Swagger und OpenAPI-Schema

Auf jeder Soulclick-Instanz stehen bereit:

Was	Adresse
Swagger-UI	`https://<deine-instanz>/api/swagger/`. Wähle oben die Version, melde dich unter Authorize an und teste Anfragen direkt gegen deine Instanz
OpenAPI-Schema	`https://<deine-instanz>/api/<version>/schema/`

Die interaktive API-Referenz beschreibt dieselben Endpunkte.

Frühere Präfixe

Die CRM-Endpunkte waren früher unter einem eigenen Präfix erreichbar. Dieses bleibt unverändert aktiv, damit bestehende Integrationen weiterlaufen. Für neue Integrationen gilt der versionierte Root.

Bisher	Neu
`/crm-api/<endpunkt>/`	`/api/<version>/crm/<endpunkt>/`

Die Stammdaten eines Kontakts und die Newsletter-Anmeldungen gibt es nur unter dem versionierten Root.

Die Swagger-UI unter /crm-api/swagger/ bleibt ebenfalls erreichbar und ist dort als Legacy gekennzeichnet.