---
updatedAt: 2026-08-27T09:05:57.000Z
agentTools:
  projectIndex: https://docs.soulclick.ch/llms.txt
---

# Spenden eines Kontakts abrufen

Liest alle Spenden einer einzelnen Person.

Der Kontakt wird über eine der beiden Kennungen bestimmt:
- **contact_id**: eindeutige Datenbank-ID des Kontakts
- **email**: E-Mail-Adresse des Kontakts

Mindestens eine der beiden ist erforderlich. Sind beide gesetzt, gilt die contact_id.

Die Antwort enthält alle Spendenarten, sortiert nach Erstellungsdatum, neueste zuerst.

## Authentifizierung

Zwei Methoden stehen zur Verfügung:
- **JWT Token**: Header `Authorization: Bearer <token>`
- **Basic Auth**: Header `Authorization: Basic <base64(benutzername:passwort)>`

Beide setzen ein Konto mit Admin-Rechten voraus.

# 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/<id>/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 <token>`\n\n2. **HTTP Basic Auth**\n   - Header: `Authorization: Basic <base64(benutzername:passwort)>`\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/contact/donations/": {
      "get": {
        "operationId": "api_v1_crm_contact_donations_retrieve",
        "description": "Liest alle Spenden einer einzelnen Person.\n\nDer Kontakt wird über eine der beiden Kennungen bestimmt:\n- **contact_id**: eindeutige Datenbank-ID des Kontakts\n- **email**: E-Mail-Adresse des Kontakts\n\nMindestens eine der beiden ist erforderlich. Sind beide gesetzt, gilt die contact_id.\n\nDie Antwort enthält alle Spendenarten, sortiert nach Erstellungsdatum, neueste zuerst.\n\n## Authentifizierung\n\nZwei Methoden stehen zur Verfügung:\n- **JWT Token**: Header `Authorization: Bearer <token>`\n- **Basic Auth**: Header `Authorization: Basic <base64(benutzername:passwort)>`\n\nBeide setzen ein Konto mit Admin-Rechten voraus.",
        "summary": "Spenden eines Kontakts abrufen",
        "parameters": [
          {
            "in": "query",
            "name": "contact_id",
            "schema": {
              "type": "integer"
            },
            "description": "Eindeutige Kennung des Kontakts",
            "examples": {
              "ContactID": {
                "value": 12345,
                "summary": "Kontakt-ID",
                "description": "Datenbank-ID des Kontakts"
              }
            }
          },
          {
            "in": "query",
            "name": "email",
            "schema": {
              "type": "string"
            },
            "description": "E-Mail-Adresse des Kontakts (gilt, wenn keine contact_id gesetzt ist)",
            "examples": {
              "EmailAddress": {
                "value": "max.muster@example.com",
                "summary": "E-Mail-Adresse",
                "description": "E-Mail-Adresse des Kontakts"
              }
            }
          },
          {
            "in": "query",
            "name": "environment",
            "schema": {
              "type": "string",
              "enum": [
                "PRODUCTION",
                "TEST"
              ]
            },
            "description": "Umgebung, aus der gelesen wird (ohne Angabe: beide)",
            "examples": {
              "AllEnvironments": {
                "summary": "Alle Umgebungen",
                "description": "TEST und PRODUCTION abfragen"
              },
              "ProductionOnly": {
                "value": "PRODUCTION",
                "summary": "Nur Produktivumgebung",
                "description": "Nur Spenden aus der Produktivumgebung"
              }
            }
          }
        ],
        "tags": [
          "Spenden"
        ],
        "security": [
          {
            "AdminJWTAuth": []
          },
          {
            "AdminBasicAuth": []
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponseSchema"
                },
                "examples": {
                  "SuccessfulResponse": {
                    "value": {
                      "contact_id": 12345,
                      "contact_type": "private",
                      "gender": "male",
                      "company": "",
                      "email": "max.muster@example.com",
                      "first_name": "Max",
                      "last_name": "Muster",
                      "postal_code": "8000",
                      "city": "Zürich",
                      "street": "Bahnhofstrasse",
                      "street_number": "1",
                      "po_box": "",
                      "country": "CH",
                      "language": "de",
                      "total_donations": 3,
                      "total_amount": {
                        "CHF": "250.00",
                        "EUR": "50.00"
                      },
                      "donations": [
                        {
                          "environment": "PRODUCTION",
                          "id": "ORD-2024-001234",
                          "initial_order_nr": "",
                          "created_at": "2024-06-15T14:30:00Z",
                          "amount": "50.00",
                          "currency": "CHF",
                          "campaign": {
                            "id": 42,
                            "title": "General Donation"
                          },
                          "purpose": "Wildlife Conservation",
                          "payment": {
                            "transaction_id": "TXN123456",
                            "method": "VIS",
                            "status": "completed",
                            "paid_out_amount": 47.85,
                            "fee_amount": 2.15,
                            "reconciled": true
                          },
                          "invoice": null,
                          "payment_type": "single",
                          "payment_interval": null
                        },
                        {
                          "environment": "PRODUCTION",
                          "id": "ORD-2024-001100",
                          "initial_order_nr": "",
                          "created_at": "2024-03-01T10:00:00Z",
                          "amount": "100.00",
                          "currency": "CHF",
                          "campaign": {
                            "id": 43,
                            "title": "Monthly Support"
                          },
                          "purpose": "Education Programs",
                          "payment": {
                            "transaction_id": "TXN789012",
                            "method": "TWI",
                            "status": "completed",
                            "paid_out_amount": 96.5,
                            "fee_amount": 3.5,
                            "reconciled": true
                          },
                          "invoice": null,
                          "payment_type": "recurring_init",
                          "payment_interval": "monthly"
                        }
                      ]
                    },
                    "summary": "Erfolgreiche Antwort"
                  }
                }
              }
            },
            "description": ""
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponseSchema"
                },
                "examples": {
                  "MissingIdentifier": {
                    "value": {
                      "error": "please provide either contact_id or email"
                    },
                    "summary": "Fehlende Kennung"
                  }
                }
              }
            },
            "description": ""
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {},
                  "description": "Inhalt nicht näher beschrieben"
                }
              }
            },
            "description": ""
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {},
                  "description": "Inhalt nicht näher beschrieben"
                }
              }
            },
            "description": ""
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {},
                  "description": "Inhalt nicht näher beschrieben"
                },
                "examples": {
                  "ContactNotFound": {
                    "value": {
                      "error": "Contact not found"
                    },
                    "summary": "Kontakt nicht gefunden"
                  }
                }
              }
            },
            "description": ""
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CampaignSchema": {
        "type": "object",
        "description": "Angaben zur Spendenaktion einer Spende.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Datenbank-ID der Spendenaktion"
          },
          "title": {
            "type": "string",
            "description": "Titel der Spendenaktion"
          }
        },
        "required": [
          "id",
          "title"
        ]
      },
      "ContactDonationDetailSchema": {
        "type": "object",
        "description": "Eine einzelne Spende eines Kontakts.",
        "properties": {
          "environment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EnvironmentEnum"
              }
            ],
            "description": "Umgebung, in der die Spende verarbeitet wurde\n\n* `TEST` - TEST\n* `PRODUCTION` - PRODUCTION"
          },
          "id": {
            "type": "string",
            "description": "Eindeutige Bestellnummer"
          },
          "initial_order_nr": {
            "type": "string",
            "description": "Bestellnummer der ersten Zahlung einer Dauerspende"
          },
          "created_at": {
            "type": "string",
            "description": "Datum und Zeit der Zahlung (Format ISO 8601)"
          },
          "amount": {
            "type": "string",
            "description": "Spendenbetrag. Ab `v2.1`: was bezahlt wurde, inklusive der von der spendenden Person übernommenen Gebühren, in `currency`."
          },
          "currency": {
            "type": "string",
            "description": "Währungscode (z. B. CHF, EUR, USD)"
          },
          "campaign": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CampaignSchema"
              }
            ],
            "nullable": true,
            "description": "Angaben zur Spendenaktion"
          },
          "purpose": {
            "type": "string",
            "nullable": true,
            "description": "Spendenzweck"
          },
          "payment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PaymentSchema"
              }
            ],
            "description": "Angaben zur Zahlung"
          },
          "invoice": {
            "type": "string",
            "nullable": true,
            "description": "Referenznummer der QR-Rechnung"
          },
          "payment_type": {
            "nullable": true,
            "description": "Art der Zahlung\n\n* `single` - single\n* `recurring_init` - recurring_init\n* `recurring_interval` - recurring_interval\n* `crowdfunding` - crowdfunding",
            "oneOf": [
              {
                "$ref": "#/components/schemas/PaymentType10fEnum"
              },
              {
                "$ref": "#/components/schemas/NullEnum"
              }
            ]
          },
          "payment_interval": {
            "type": "string",
            "nullable": true,
            "description": "Intervall der Dauerspende"
          }
        },
        "required": [
          "amount",
          "campaign",
          "created_at",
          "currency",
          "environment",
          "id",
          "initial_order_nr",
          "invoice",
          "payment",
          "payment_interval",
          "payment_type",
          "purpose"
        ]
      },
      "ContactResponseSchema": {
        "type": "object",
        "description": "Die Spenden eines Kontakts.\n\nEnthält die Angaben zum Kontakt, alle Spenden und die Kennzahlen dazu.",
        "properties": {
          "contact_id": {
            "type": "integer",
            "description": "Eindeutige Kennung des Kontakts"
          },
          "contact_type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ContactTypeEnum"
              }
            ],
            "description": "Art des Kontakts: private oder company\n\n* `private` - private\n* `company` - company"
          },
          "gender": {
            "type": "string",
            "description": "Anrede des Kontakts (male, female, prefer-not-to-say)"
          },
          "company": {
            "type": "string",
            "description": "Firmenname (nur bei Firmenkontakten)"
          },
          "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"
          },
          "postal_code": {
            "type": "string",
            "description": "Postleitzahl"
          },
          "city": {
            "type": "string",
            "description": "Ort"
          },
          "street": {
            "type": "string",
            "description": "Strasse"
          },
          "street_number": {
            "type": "string",
            "description": "Hausnummer"
          },
          "po_box": {
            "type": "string",
            "description": "Postfach oder Adresszusatz"
          },
          "country": {
            "type": "string",
            "description": "Ländercode nach ISO 3166-1 alpha-2"
          },
          "language": {
            "type": "string",
            "description": "Bevorzugte Korrespondenzsprache"
          },
          "total_donations": {
            "type": "integer",
            "description": "Anzahl Spenden dieses Kontakts"
          },
          "total_amount": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Spendensummen pro Währung"
          },
          "donations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactDonationDetailSchema"
            },
            "description": "Alle Spenden dieses Kontakts"
          }
        },
        "required": [
          "city",
          "company",
          "contact_id",
          "contact_type",
          "country",
          "donations",
          "email",
          "first_name",
          "gender",
          "language",
          "last_name",
          "po_box",
          "postal_code",
          "street",
          "street_number",
          "total_amount",
          "total_donations"
        ]
      },
      "ContactTypeEnum": {
        "enum": [
          "private",
          "company"
        ],
        "type": "string",
        "description": "* `private` - private\n* `company` - company"
      },
      "EnvironmentEnum": {
        "enum": [
          "TEST",
          "PRODUCTION"
        ],
        "type": "string",
        "description": "* `TEST` - TEST\n* `PRODUCTION` - PRODUCTION"
      },
      "ErrorResponseSchema": {
        "type": "object",
        "description": "Antwort im Fehlerfall.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Fehlermeldung mit der Ursache"
          }
        },
        "required": [
          "error"
        ]
      },
      "NullEnum": {
        "enum": [
          null
        ]
      },
      "PaymentSchema": {
        "type": "object",
        "description": "Angaben zur Zahlung einer Spende.",
        "properties": {
          "transaction_id": {
            "type": "string",
            "description": "Transaktions-ID der Zahlung"
          },
          "method": {
            "type": "string",
            "description": "Verwendete Zahlungsart (z. B. VIS, ECA, TWI, PAP, INV)"
          },
          "status": {
            "type": "string",
            "description": "Zahlungsstatus (completed oder pending)"
          },
          "paid_out_amount": {
            "type": "number",
            "format": "double",
            "nullable": true,
            "description": "Von Stripe ausgezahlter Netto-Betrag nach Gebühren (null ohne Stripe oder vor dem Abgleich)"
          },
          "fee_amount": {
            "type": "number",
            "format": "double",
            "nullable": true,
            "description": "Von Stripe abgezogene Gebühr (null ohne Stripe oder vor dem Abgleich)"
          },
          "reconciled": {
            "type": "boolean",
            "description": "Ob die Zahlung mit den BalanceTransaction-Daten von Stripe abgeglichen ist"
          }
        },
        "required": [
          "fee_amount",
          "method",
          "paid_out_amount",
          "reconciled",
          "status",
          "transaction_id"
        ]
      },
      "PaymentType10fEnum": {
        "enum": [
          "single",
          "recurring_init",
          "recurring_interval",
          "crowdfunding"
        ],
        "type": "string",
        "description": "* `single` - single\n* `recurring_init` - recurring_init\n* `recurring_interval` - recurring_interval\n* `crowdfunding` - crowdfunding"
      }
    },
    "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": "Spenden",
      "description": "Spendendaten lesen"
    }
  ]
}
```