--- updatedAt: 2026-08-27T09:05:57.000Z agentTools: projectIndex: https://docs.soulclick.ch/llms.txt --- # Kontakte abrufen Liest die Kontakte mit ihrer Spendenstatistik. Der Endpunkt liefert eine seitenweise Liste aller Personen, die gespendet haben, samt Kennzahlen wie Anzahl und Summe ihrer Spenden. ## Authentifizierung Zwei Methoden stehen zur Verfügung: - **JWT Token**: Header `Authorization: Bearer ` - **Basic Auth**: Header `Authorization: Basic ` Beide setzen ein Konto mit Admin-Rechten voraus. ## Filter - **search**: Suche nach Name oder E-Mail (Teiltreffer) - **environment**: Umgebung der Spenden # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Soulclick API v1", "version": "v1", "description": "## Soulclick API\n\nDie öffentliche API einer Soulclick-Plattform: Spenden- und Kontaktdaten für Drittsysteme sowie die\nSpenden-Konfiguration von Kampagnen-Links für selbst gebaute Spenden-Teaser.\n\n**Dieses Dokument beschreibt `/api/v1/`** und listet genau die Felder auf, die diese Version\nzurückgibt. Die Versionsauswahl oben auf `/api/swagger/` wechselt zwischen den Dokumenten.\n\n### API-Root\n\nAlle öffentlichen Endpunkte liegen unter einem gemeinsamen, versionierten Root und sind nach Bereich\ngruppiert:\n\n- `/api/v1/crm/*` – Spenden- und Kontaktdaten (Authentifizierung erforderlich)\n- `/api/v1/campaign-links//config/` – öffentliche Spenden-Konfiguration eines Kampagnen-Links\n\nDie CRM-Endpunkte sind weiterhin auch unter ihrem früheren Prefix `/crm-api/*` erreichbar, das genau\nwie bisher antwortet – `v1`-Payloads – und für laufende Integrationen bestehen bleibt. Neue\nIntegrationen verwenden die neuste Version.\n\n### Authentifizierung\n\nDie CRM-Endpunkte unterstützen zwei Methoden:\n\n1. **JWT Bearer Token**\n - Token über `/authentication/create` beziehen\n - Header: `Authorization: Bearer `\n\n2. **HTTP Basic Auth**\n - Header: `Authorization: Basic `\n - Praktisch für einfache Integrationen und externe Anbieter\n\nBeide setzen ein Konto mit Admin-Rechten voraus. Die Konfiguration eines Kampagnen-Links ist\nöffentlich und benötigt keine Zugangsdaten.\n\n### Umgebungen\n\nDie CRM-Endpunkte lesen aus zwei Umgebungen:\n- `TEST` – Testdaten\n- `PRODUCTION` – echte Daten\n\n### Seitenweises Lesen\n\n`next` und `previous` verweisen auf dasselbe Prefix wie die Anfrage: ein Aufruf von\n`/api/v1/crm/contacts/` erhält wieder `/api/v1/crm/contacts/`-Links zurück, ein Aufruf\nüber das alte Prefix entsprechend alte Links.\n\n### Versionierung und Kompatibilität\n\nDie Version steht im Pfad. Jede Version bleibt verfügbar und antwortet weiterhin genau so wie zum\nZeitpunkt der Integration: ein später eingeführtes Feld kommt nicht mehr dazu.\n\n| Version | Root | Eingeführt |\n|:---|:---|:---|\n| `v1` | `/api/v1/` | Die ursprüngliche Antwort. Das liefert auch `/crm-api/*`. |\n| `v2` | `/api/v2/` | `custom_fields`: die Antworten der spendenden Person auf die eigenen Checkout-Felder der Plattform, am Kontakt einer Spende. |\n| `v2.1` | `/api/v2.1/` | `checkout` an jedem Spendeneintrag und `positions` an jeder Spende eines Kontakts: ein Multi-Checkout ist ein Eintrag mit allen Positionen. 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`. |\n\nEin Wechsel auf eine höhere Version heisst, einen anderen Root aufzurufen; an der Anfrage ändert\nsich sonst nichts, und Endpunkte, Parameter und Authentifizierung sind über alle Versionen gleich.\n\nEine Integration **muss** trotzdem:\n- unbekannte JSON-Felder ignorieren statt die Antwort abzulehnen\n- sich nicht auf die Reihenfolge der Felder verlassen\n- nicht davon ausgehen, dass die Feldliste abgeschlossen ist\n\nManche Änderungen lassen sich nicht über eine Version zurückhalten – ein neuer Enum-Wert in einem als\nerweiterbar dokumentierten Feld oder ein neuer Endpunkt – und können jederzeit erscheinen. Ein\n**Breaking Change** (ein Feld entfernen oder umbenennen, den Typ eines Feldes ändern, ein Feld\nerforderlich oder optional machen, die Authentifizierung ändern) kommt in die nächste Version und\nwird vorab über den vereinbarten Support-Kanal angekündigt und abgestimmt." }, "paths": { "/api/v1/crm/contacts/": { "get": { "operationId": "api_v1_crm_contacts_retrieve", "description": "Liest die Kontakte mit ihrer Spendenstatistik.\n\nDer Endpunkt liefert eine seitenweise Liste aller Personen, die gespendet haben, samt Kennzahlen\nwie Anzahl und Summe ihrer Spenden.\n\n## Authentifizierung\n\nZwei Methoden stehen zur Verfügung:\n- **JWT Token**: Header `Authorization: Bearer `\n- **Basic Auth**: Header `Authorization: Basic `\n\nBeide setzen ein Konto mit Admin-Rechten voraus.\n\n## Filter\n\n- **search**: Suche nach Name oder E-Mail (Teiltreffer)\n- **environment**: Umgebung der Spenden", "summary": "Kontakte abrufen", "parameters": [ { "in": "query", "name": "environment", "schema": { "type": "string", "enum": [ "PRODUCTION", "TEST" ] }, "description": "Nur Kontakte mit Spenden in dieser Umgebung" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50 }, "description": "Maximale Anzahl Ergebnisse" }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0 }, "description": "Anzahl übersprungener Ergebnisse (Seitenwechsel)" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Kontakte nach Name oder E-Mail suchen (Teiltreffer)", "examples": { "SearchByName": { "value": "Muster", "summary": "Suche nach Name", "description": "Kontakte mit „Muster“ im Namen" }, "SearchByEmail": { "value": "@example.com", "summary": "Suche nach E-Mail", "description": "Kontakte mit „@example.com“ in der E-Mail-Adresse" } } } ], "tags": [ "Kontakte" ], "security": [ { "AdminJWTAuth": [] }, { "AdminBasicAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListResponseSchema" }, "examples": { "SuccessfulResponse": { "value": { "count": 150, "next": "/api/v1/crm/contacts/?limit=50&offset=50", "previous": null, "results": [ { "contact_id": 12345, "email": "max.muster@example.com", "first_name": "Max", "last_name": "Muster", "contact_type": "private", "total_donations": 5, "total_amount": { "CHF": "350.00" } }, { "contact_id": 12346, "email": "anna.mueller@example.com", "first_name": "Anna", "last_name": "Müller", "contact_type": "private", "total_donations": 3, "total_amount": { "CHF": "150.00", "EUR": "50.00" } } ] }, "summary": "Erfolgreiche Antwort" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseSchema" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseSchema" }, "examples": { "Unauthorized": { "value": { "error": "Authentication credentials were not provided." } } } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseSchema" }, "examples": { "Forbidden": { "value": { "error": "Admin access required." } } } } }, "description": "" } } } } }, "components": { "schemas": { "ContactListResponseSchema": { "type": "object", "description": "Seitenweise Kontaktliste.", "properties": { "count": { "type": "integer", "description": "Anzahl Kontakte, die der Abfrage entsprechen" }, "next": { "type": "string", "nullable": true, "description": "URL der nächsten Seite (null auf der letzten Seite)" }, "previous": { "type": "string", "nullable": true, "description": "URL der vorherigen Seite (null auf der ersten Seite)" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ContactSummarySchema" }, "description": "Kontakte mit ihrer Spendenstatistik" } }, "required": [ "count", "next", "previous", "results" ] }, "ContactSummarySchema": { "type": "object", "description": "Ein Kontakt in der Kontaktliste.", "properties": { "contact_id": { "type": "integer", "description": "Eindeutige Kennung des Kontakts" }, "email": { "type": "string", "format": "email", "description": "E-Mail-Adresse des Kontakts" }, "first_name": { "type": "string", "description": "Vorname des Kontakts" }, "last_name": { "type": "string", "description": "Nachname des Kontakts" }, "contact_type": { "allOf": [ { "$ref": "#/components/schemas/ContactTypeEnum" } ], "description": "Art des Kontakts: private oder company\n\n* `private` - private\n* `company` - company" }, "total_donations": { "type": "integer", "description": "Anzahl Spenden dieses Kontakts" }, "total_amount": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Spendensummen pro Währung" } }, "required": [ "contact_id", "contact_type", "email", "first_name", "last_name", "total_amount", "total_donations" ] }, "ContactTypeEnum": { "enum": [ "private", "company" ], "type": "string", "description": "* `private` - private\n* `company` - company" }, "ErrorResponseSchema": { "type": "object", "description": "Antwort im Fehlerfall.", "properties": { "error": { "type": "string", "description": "Fehlermeldung mit der Ursache" } }, "required": [ "error" ] } }, "securitySchemes": { "AdminBasicAuth": { "type": "http", "scheme": "basic", "description": "Basic-Authentifizierung, erfordert Admin-Rechte" }, "AdminJWTAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT-Authentifizierung, erfordert Admin-Rechte" } } }, "tags": [ { "name": "Kontakte", "description": "Kontakte und ihre Spendenstatistik lesen" } ] } ```