Gäste-API

Die Gäste-API ermöglicht das Verwalten deiner Gästeliste über die REST-Schnittstelle. Du kannst Gäste auflisten, abrufen, erstellen, aktualisieren und löschen.

Endpunkte

Methode	Endpunkt	Beschreibung	Berechtigung
`GET`	`/api/v1/guests`	Alle Gäste auflisten	`guests:read`
`GET`	`/api/v1/guests/{id}`	Einzelnen Gast abrufen	`guests:read`
`POST`	`/api/v1/guests`	Neuen Gast erstellen	`guests:write`
`PUT`	`/api/v1/guests/{id}`	Gast aktualisieren	`guests:write`
`DELETE`	`/api/v1/guests/{id}`	Gast löschen	`guests:write`

Gast-Objekt

Jede Antwort enthält Gast-Objekte im folgenden Format:

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "Max",
  "last_name": "Mustermann",
  "email": "max@example.com",
  "phone": "+49 123 456789",
  "street": "Musterstraße 1",
  "postal_code": "12345",
  "city": "Berlin",
  "country": "Deutschland",
  "group": "bride_family",
  "rsvp_status": "confirmed",
  "rsvp_responded_at": "2026-03-15T14:30:00+00:00",
  "menu_choice": "vegetarian",
  "allergies": "Nüsse",
  "is_plus_one": false,
  "invited_by_id": null,
  "is_child": false,
  "age": null,
  "notes": "Sitzt gerne neben Anna",
  "household_id": "550e8400-e29b-41d4-a716-446655440001",
  "household": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Familie Mustermann"
  },
  "tags": ["VIP", "Vegetarier"],
  "created_at": "2026-03-01T10:00:00+00:00",
  "updated_at": "2026-03-15T14:30:00+00:00"
}

Felder

Feld	Typ	Beschreibung
`id`	`string` (UUID)	Eindeutige ID des Gastes
`first_name`	`string`	Vorname
`last_name`	`string \| null`	Nachname
`email`	`string \| null`	E-Mail-Adresse
`phone`	`string \| null`	Telefonnummer
`street`	`string \| null`	Straße und Hausnummer (nur lesbar, nicht über API setzbar)
`postal_code`	`string \| null`	Postleitzahl (nur lesbar)
`city`	`string \| null`	Stadt (nur lesbar)
`country`	`string \| null`	Land (nur lesbar, Standard: „Deutschland")
`group`	`string`	Gruppe (siehe Gruppen)
`rsvp_status`	`string`	RSVP-Status (siehe RSVP-Status)
`rsvp_responded_at`	`string \| null`	Zeitpunkt der RSVP-Antwort (ISO 8601, automatisch gesetzt)
`menu_choice`	`string \| null`	Menüwahl (siehe Menüwahl)
`allergies`	`string \| null`	Allergien oder Unverträglichkeiten (Freitext)
`is_plus_one`	`boolean`	Begleitperson eines anderen Gastes (nur lesbar)
`invited_by_id`	`string \| null` (UUID)	ID des einladenden Gastes bei Plus-One (nur lesbar)
`is_child`	`boolean`	Kind (unter 18)
`age`	`integer \| null`	Alter des Kindes (0–17)
`notes`	`string \| null`	Notizen (Freitext)
`household_id`	`string \| null` (UUID)	ID des Haushalts
`household`	`object \| null`	Haushalt-Objekt mit `id` und `name` (nur in der Antwort)
`tags`	`array`	Liste der zugewiesenen Tag-Namen (in der Antwort als Namen, im Request als UUIDs)
`created_at`	`string`	Erstellungszeitpunkt (ISO 8601)
`updated_at`	`string`	Letzter Änderungszeitpunkt (ISO 8601)

Nur-Lese-Felder

Die Felder street, postal_code, city, country, is_plus_one, invited_by_id und rsvp_responded_at werden in der Antwort zurückgegeben, können aber nicht über die API gesetzt oder geändert werden. Diese Felder werden über die Web-Oberfläche verwaltet.

Gruppen

Wert	Beschreibung
`bride_family`	Familie der Braut
`groom_family`	Familie des Bräutigams
`friends_bride`	Freunde der Braut
`friends_groom`	Freunde des Bräutigams
`colleagues`	Kollegen
`other`	Sonstige

RSVP-Status

Wert	Beschreibung
`pending`	Ausstehend (Standardwert)
`confirmed`	Zugesagt
`declined`	Abgesagt
`no_response`	Keine Antwort

Menüwahl

Wert	Beschreibung
`standard`	Standardmenü
`vegetarian`	Vegetarisch
`vegan`	Vegan
`child`	Kindermenü

Alle Gäste auflisten

Gibt alle Gäste der aktiven Hochzeit zurück, sortiert nach Nachname und Vorname.

GET /api/v1/guests

Berechtigung: guests:read

Beispiel-Request

bash

curl -X GET https://hochzeitshelfer.app/api/v1/guests \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"

Beispiel-Antwort

Status: 200 OK

json

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "Anna",
      "last_name": "Becker",
      "email": "anna@example.com",
      "phone": null,
      "street": null,
      "postal_code": null,
      "city": null,
      "country": "Deutschland",
      "group": "friends_bride",
      "rsvp_status": "confirmed",
      "rsvp_responded_at": "2026-03-10T09:00:00+00:00",
      "menu_choice": "vegan",
      "allergies": null,
      "is_plus_one": false,
      "invited_by_id": null,
      "is_child": false,
      "age": null,
      "notes": null,
      "household_id": null,
      "household": null,
      "tags": ["Trauzeugin"],
      "created_at": "2026-02-01T12:00:00+00:00",
      "updated_at": "2026-03-10T09:00:00+00:00"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "first_name": "Max",
      "last_name": "Mustermann",
      "email": "max@example.com",
      "phone": "+49 123 456789",
      "street": "Musterstraße 1",
      "postal_code": "12345",
      "city": "Berlin",
      "country": "Deutschland",
      "group": "bride_family",
      "rsvp_status": "pending",
      "rsvp_responded_at": null,
      "menu_choice": null,
      "allergies": "Nüsse",
      "is_plus_one": false,
      "invited_by_id": null,
      "is_child": false,
      "age": null,
      "notes": "Onkel der Braut",
      "household_id": "770e8400-e29b-41d4-a716-446655440000",
      "household": {
        "id": "770e8400-e29b-41d4-a716-446655440000",
        "name": "Familie Mustermann"
      },
      "tags": ["VIP"],
      "created_at": "2026-02-01T12:00:00+00:00",
      "updated_at": "2026-02-01T12:00:00+00:00"
    }
  ]
}

Einzelnen Gast abrufen

Gibt einen einzelnen Gast anhand seiner ID zurück.

GET /api/v1/guests/{id}

Berechtigung: guests:read

Parameter

Parameter	Typ	Beschreibung
`id`	`string` (UUID)	ID des Gastes (Pfadparameter)

Beispiel-Request

bash

curl -X GET https://hochzeitshelfer.app/api/v1/guests/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"

Beispiel-Antwort

Status: 200 OK

json

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "Anna",
    "last_name": "Becker",
    "email": "anna@example.com",
    "phone": null,
    "street": null,
    "postal_code": null,
    "city": null,
    "country": "Deutschland",
    "group": "friends_bride",
    "rsvp_status": "confirmed",
    "rsvp_responded_at": "2026-03-10T09:00:00+00:00",
    "menu_choice": "vegan",
    "allergies": null,
    "is_plus_one": false,
    "invited_by_id": null,
    "is_child": false,
    "age": null,
    "notes": null,
    "household_id": null,
    "household": null,
    "tags": ["Trauzeugin"],
    "created_at": "2026-02-01T12:00:00+00:00",
    "updated_at": "2026-03-10T09:00:00+00:00"
  }
}

Fehler

Status	Ursache
`404 Not Found`	Gast mit dieser ID existiert nicht
`403 Forbidden`	Gast gehört zu einer anderen Hochzeit

Neuen Gast erstellen

Erstellt einen neuen Gast in der aktiven Hochzeit.

POST /api/v1/guests

Berechtigung: guests:write

Request-Body — Alle verfügbaren Felder

Feld	Typ	Pflicht	Standardwert	Beschreibung
`first_name`	`string`	Ja	—	Vorname (max. 255 Zeichen)
`last_name`	`string \| null`	Nein	`null`	Nachname (max. 255 Zeichen)
`email`	`string \| null`	Nein	`null`	Gültige E-Mail-Adresse (max. 255 Zeichen)
`phone`	`string \| null`	Nein	`null`	Telefonnummer (max. 255 Zeichen)
`group`	`string`	Nein	`"other"`	Gruppe: `bride_family`, `groom_family`, `friends_bride`, `friends_groom`, `colleagues`, `other`
`rsvp_status`	`string`	Nein	`"pending"`	Status: `pending`, `confirmed`, `declined`, `no_response`
`menu_choice`	`string \| null`	Nein	`null`	Menü: `standard`, `vegetarian`, `vegan`, `child`
`allergies`	`string \| null`	Nein	`null`	Freitext für Allergien und Unverträglichkeiten
`notes`	`string \| null`	Nein	`null`	Freitext-Notizen zum Gast
`is_child`	`boolean`	Nein	`false`	Markiert den Gast als Kind (unter 18 Jahre)
`age`	`integer \| null`	Nein	`null`	Alter des Kindes (0–17). Nur sinnvoll zusammen mit `is_child: true`
`household_id`	`string \| null` (UUID)	Nein	`null`	UUID eines bestehenden Haushalts, um den Gast zuzuordnen
`tags`	`array`	Nein	`[]`	Array von Tag-UUIDs. Nur Tags, die zur Hochzeit gehören, werden zugewiesen

Beispiel: Minimaler Request (nur Pflichtfelder)

Der einfachste Request benötigt nur den Vornamen. Alle anderen Felder erhalten ihre Standardwerte.

bash

curl -X POST https://hochzeitshelfer.app/api/v1/guests \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Lisa"
  }'

Antwort: 200 OK

json

{
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440000",
    "first_name": "Lisa",
    "last_name": null,
    "email": null,
    "phone": null,
    "street": null,
    "postal_code": null,
    "city": null,
    "country": "Deutschland",
    "group": "other",
    "rsvp_status": "pending",
    "rsvp_responded_at": null,
    "menu_choice": null,
    "allergies": null,
    "is_plus_one": false,
    "invited_by_id": null,
    "is_child": false,
    "age": null,
    "notes": null,
    "household_id": null,
    "household": null,
    "tags": [],
    "created_at": "2026-03-18T10:00:00+00:00",
    "updated_at": "2026-03-18T10:00:00+00:00"
  }
}

Beispiel: Vollständiger Request (alle Felder)

Ein Request mit allen verfügbaren Feldern:

bash

curl -X POST https://hochzeitshelfer.app/api/v1/guests \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Lisa",
    "last_name": "Schmidt",
    "email": "lisa.schmidt@example.com",
    "phone": "+49 171 1234567",
    "group": "friends_bride",
    "rsvp_status": "confirmed",
    "menu_choice": "vegetarian",
    "allergies": "Laktoseintoleranz, Glutenunverträglichkeit",
    "notes": "Bringt selbstgemachten Kuchen mit. Sitzt gerne neben Anna.",
    "is_child": false,
    "age": null,
    "household_id": "770e8400-e29b-41d4-a716-446655440000",
    "tags": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ]
  }'

Antwort: 200 OK

json

{
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440000",
    "first_name": "Lisa",
    "last_name": "Schmidt",
    "email": "lisa.schmidt@example.com",
    "phone": "+49 171 1234567",
    "street": null,
    "postal_code": null,
    "city": null,
    "country": "Deutschland",
    "group": "friends_bride",
    "rsvp_status": "confirmed",
    "rsvp_responded_at": null,
    "menu_choice": "vegetarian",
    "allergies": "Laktoseintoleranz, Glutenunverträglichkeit",
    "is_plus_one": false,
    "invited_by_id": null,
    "is_child": false,
    "age": null,
    "notes": "Bringt selbstgemachten Kuchen mit. Sitzt gerne neben Anna.",
    "household_id": "770e8400-e29b-41d4-a716-446655440000",
    "household": {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "Familie Müller"
    },
    "tags": ["VIP", "Vegetarier"],
    "created_at": "2026-03-18T10:00:00+00:00",
    "updated_at": "2026-03-18T10:00:00+00:00"
  }
}

Beispiel: Kind anlegen

Kinder werden mit is_child: true markiert. Optional kann das age-Feld (0–17) gesetzt werden, z. B. um das passende Kindermenü zuzuordnen.

bash

curl -X POST https://hochzeitshelfer.app/api/v1/guests \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Emma",
    "last_name": "Mustermann",
    "group": "bride_family",
    "is_child": true,
    "age": 5,
    "menu_choice": "child",
    "allergies": "Nussallergie",
    "household_id": "770e8400-e29b-41d4-a716-446655440000",
    "notes": "Braucht einen Kindersitz"
  }'

Antwort: 200 OK

json

{
  "data": {
    "id": "aa0e8400-e29b-41d4-a716-446655440000",
    "first_name": "Emma",
    "last_name": "Mustermann",
    "group": "bride_family",
    "rsvp_status": "pending",
    "menu_choice": "child",
    "allergies": "Nussallergie",
    "is_child": true,
    "age": 5,
    "notes": "Braucht einen Kindersitz",
    "household_id": "770e8400-e29b-41d4-a716-446655440000",
    "household": {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "Familie Mustermann"
    },
    "tags": [],
    "..."
  }
}

Beispiel: Gast mit Haushalt anlegen

Ein Haushalt gruppiert Gäste, die zusammengehören (z. B. eine Familie oder ein Paar). Mehrere Gäste können derselben household_id zugeordnet werden.

Haushalte

Haushalte werden über die Web-Oberfläche erstellt und haben eine UUID. Du findest die household_id bestehender Haushalte in der Antwort anderer Gäste, die bereits einem Haushalt zugeordnet sind.

bash

# Ersten Gast im Haushalt anlegen
curl -X POST https://hochzeitshelfer.app/api/v1/guests \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Thomas",
    "last_name": "Müller",
    "email": "thomas.mueller@example.com",
    "group": "groom_family",
    "household_id": "770e8400-e29b-41d4-a716-446655440000"
  }'

# Zweiten Gast im selben Haushalt anlegen
curl -X POST https://hochzeitshelfer.app/api/v1/guests \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Sabine",
    "last_name": "Müller",
    "email": "sabine.mueller@example.com",
    "group": "groom_family",
    "household_id": "770e8400-e29b-41d4-a716-446655440000"
  }'

Beide Gäste sind nun über die gemeinsame household_id verknüpft.

Beispiel: Gast mit Tags anlegen

Tags sind Markierungen, die du Gästen zuweisen kannst (z. B. „VIP", „Vegetarier", „Rollstuhl"). Tags werden über die Web-Oberfläche erstellt und verwaltet.

Im API-Request sendest du die UUIDs der Tags. In der Antwort erhältst du die Namen der Tags zurück.

Wichtig

Nur Tags, die zur aktuellen Hochzeit gehören, werden zugewiesen. Ungültige oder fremde UUIDs werden stillschweigend ignoriert.

bash

curl -X POST https://hochzeitshelfer.app/api/v1/guests \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Claudia",
    "last_name": "Weber",
    "group": "friends_groom",
    "tags": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ]
  }'

Antwort:

json

{
  "data": {
    "first_name": "Claudia",
    "last_name": "Weber",
    "group": "friends_groom",
    "tags": ["VIP", "Vegetarier"],
    "..."
  }
}

Beispiel mit JavaScript (vollständig)

javascript

const response = await fetch('https://hochzeitshelfer.app/api/v1/guests', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Lisa',
    last_name: 'Schmidt',
    email: 'lisa@example.com',
    phone: '+49 171 1234567',
    group: 'friends_bride',
    rsvp_status: 'pending',
    menu_choice: 'vegetarian',
    allergies: 'Laktoseintoleranz',
    notes: 'Beste Freundin der Braut',
    is_child: false,
    household_id: '770e8400-e29b-41d4-a716-446655440000',
    tags: ['a1b2c3d4-e5f6-7890-abcd-ef1234567890'],
  }),
});

const data = await response.json();
console.log('Neuer Gast:', data.data.id);

Beispiel mit Python (vollständig)

python

import requests

headers = {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
}

payload = {
    'first_name': 'Lisa',
    'last_name': 'Schmidt',
    'email': 'lisa@example.com',
    'phone': '+49 171 1234567',
    'group': 'friends_bride',
    'rsvp_status': 'pending',
    'menu_choice': 'vegetarian',
    'allergies': 'Laktoseintoleranz',
    'notes': 'Beste Freundin der Braut',
    'is_child': False,
    'household_id': '770e8400-e29b-41d4-a716-446655440000',
    'tags': ['a1b2c3d4-e5f6-7890-abcd-ef1234567890'],
}

response = requests.post(
    'https://hochzeitshelfer.app/api/v1/guests',
    headers=headers,
    json=payload,
)

data = response.json()
print(f"Neuer Gast: {data['data']['id']}")

Beispiel mit PHP (vollständig)

php

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://hochzeitshelfer.app/api/v1/guests', [
    'headers' => [
        'Authorization' => 'Bearer DEIN_API_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'first_name' => 'Lisa',
        'last_name' => 'Schmidt',
        'email' => 'lisa@example.com',
        'phone' => '+49 171 1234567',
        'group' => 'friends_bride',
        'rsvp_status' => 'pending',
        'menu_choice' => 'vegetarian',
        'allergies' => 'Laktoseintoleranz',
        'notes' => 'Beste Freundin der Braut',
        'is_child' => false,
        'household_id' => '770e8400-e29b-41d4-a716-446655440000',
        'tags' => ['a1b2c3d4-e5f6-7890-abcd-ef1234567890'],
    ],
]);

$data = json_decode($response->getBody(), true);
echo 'Neuer Gast: ' . $data['data']['id'];

Validierungsfehler

Status: 422 Unprocessable Entity

json

{
  "message": "The given data was invalid.",
  "errors": {
    "first_name": ["The first name field is required."],
    "group": ["The selected group is invalid."],
    "age": ["The age field must be between 0 and 17."],
    "email": ["The email field must be a valid email address."],
    "tags.0": ["The tags.0 field must be a valid UUID."]
  }
}

Gast aktualisieren

Aktualisiert einen bestehenden Gast. Es müssen nur die zu ändernden Felder gesendet werden (Partial Update). Nicht mitgesendete Felder bleiben unverändert.

PUT /api/v1/guests/{id}

Berechtigung: guests:write

Parameter

Parameter	Typ	Beschreibung
`id`	`string` (UUID)	ID des Gastes (Pfadparameter)

Request-Body — Alle verfügbaren Felder

Alle Felder sind optional. Nur die gesendeten Felder werden aktualisiert.

Feld	Typ	Beschreibung
`first_name`	`string`	Vorname (max. 255 Zeichen)
`last_name`	`string \| null`	Nachname (max. 255 Zeichen)
`email`	`string \| null`	E-Mail-Adresse
`phone`	`string \| null`	Telefonnummer
`group`	`string`	Gruppe: `bride_family`, `groom_family`, `friends_bride`, `friends_groom`, `colleagues`, `other`
`rsvp_status`	`string`	Status: `pending`, `confirmed`, `declined`, `no_response`
`menu_choice`	`string \| null`	Menü: `standard`, `vegetarian`, `vegan`, `child`
`allergies`	`string \| null`	Allergien/Unverträglichkeiten
`notes`	`string \| null`	Notizen
`is_child`	`boolean`	Kind (unter 18)
`age`	`integer \| null`	Alter (0–17)
`household_id`	`string \| null` (UUID)	Haushalts-ID (auf `null` setzen, um den Gast aus dem Haushalt zu entfernen)
`tags`	`array` von UUIDs	Tag-IDs (ersetzt alle bisherigen Tags des Gastes)

Tags-Verhalten bei Updates

Wenn du das tags-Feld im Update-Request mitsendest, werden alle bisherigen Tags des Gastes durch die neue Liste ersetzt (Sync-Verhalten). Um die bestehenden Tags beizubehalten, sende das tags-Feld einfach nicht mit.

tags nicht mitgesendet → Tags bleiben unverändert
tags: [] → Alle Tags werden entfernt
tags: ["uuid-1", "uuid-2"] → Genau diese Tags werden zugewiesen (alle vorherigen entfernt)

Beispiel: Einzelnes Feld ändern

Der einfachste Fall — nur ein Feld aktualisieren:

bash

curl -X PUT https://hochzeitshelfer.app/api/v1/guests/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "rsvp_status": "confirmed"
  }'

Beispiel: RSVP-Zusage mit Menüwahl

Typischer Anwendungsfall: Ein Gast sagt zu und teilt seine Menüwahl mit.

bash

curl -X PUT https://hochzeitshelfer.app/api/v1/guests/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "rsvp_status": "confirmed",
    "menu_choice": "vegan",
    "allergies": "Nussallergie, Sojaallergie"
  }'

Antwort: 200 OK

json

{
  "data": {
    "id": "880e8400-e29b-41d4-a716-446655440000",
    "first_name": "Lisa",
    "last_name": "Schmidt",
    "email": "lisa@example.com",
    "phone": "+49 171 1234567",
    "street": null,
    "postal_code": null,
    "city": null,
    "country": "Deutschland",
    "group": "friends_bride",
    "rsvp_status": "confirmed",
    "rsvp_responded_at": null,
    "menu_choice": "vegan",
    "allergies": "Nussallergie, Sojaallergie",
    "is_plus_one": false,
    "invited_by_id": null,
    "is_child": false,
    "age": null,
    "notes": "Beste Freundin der Braut",
    "household_id": "770e8400-e29b-41d4-a716-446655440000",
    "household": {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "Familie Müller"
    },
    "tags": ["VIP"],
    "created_at": "2026-03-18T10:00:00+00:00",
    "updated_at": "2026-03-18T14:30:00+00:00"
  }
}

Beispiel: Gast in einen Haushalt verschieben

bash

curl -X PUT https://hochzeitshelfer.app/api/v1/guests/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "household_id": "770e8400-e29b-41d4-a716-446655440000"
  }'

Beispiel: Gast aus Haushalt entfernen

Setze household_id auf null, um den Gast aus dem Haushalt zu lösen:

bash

curl -X PUT https://hochzeitshelfer.app/api/v1/guests/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "household_id": null
  }'

Beispiel: Tags aktualisieren

Tags des Gastes komplett ersetzen:

bash

curl -X PUT https://hochzeitshelfer.app/api/v1/guests/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "c3d4e5f6-a7b8-9012-cdef-123456789012"
    ]
  }'

Alle Tags entfernen:

bash

curl -X PUT https://hochzeitshelfer.app/api/v1/guests/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": []
  }'

Beispiel: Kind-Status setzen

Einen bestehenden Gast als Kind markieren und das Alter eintragen:

bash

curl -X PUT https://hochzeitshelfer.app/api/v1/guests/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "is_child": true,
    "age": 8,
    "menu_choice": "child"
  }'

Beispiel: Vollständiges Update (alle Felder)

bash

curl -X PUT https://hochzeitshelfer.app/api/v1/guests/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Elisabeth",
    "last_name": "Schmidt-Müller",
    "email": "elisabeth@example.com",
    "phone": "+49 171 9876543",
    "group": "bride_family",
    "rsvp_status": "confirmed",
    "menu_choice": "vegetarian",
    "allergies": "Laktose",
    "notes": "Hat den Nachnamen geändert. Sitzt am Familientisch.",
    "is_child": false,
    "age": null,
    "household_id": "770e8400-e29b-41d4-a716-446655440000",
    "tags": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }'

Beispiel: Feld auf null setzen

Um ein optionales Feld zu leeren, sende explizit null:

bash

curl -X PUT https://hochzeitshelfer.app/api/v1/guests/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": null,
    "phone": null,
    "allergies": null,
    "menu_choice": null,
    "notes": null
  }'

Beispiel mit JavaScript (vollständig)

javascript

const guestId = '880e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://hochzeitshelfer.app/api/v1/guests/${guestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    first_name: 'Elisabeth',
    last_name: 'Schmidt-Müller',
    email: 'elisabeth@example.com',
    phone: '+49 171 9876543',
    group: 'bride_family',
    rsvp_status: 'confirmed',
    menu_choice: 'vegetarian',
    allergies: 'Laktose',
    notes: 'Hat den Nachnamen geändert',
    is_child: false,
    age: null,
    household_id: '770e8400-e29b-41d4-a716-446655440000',
    tags: ['a1b2c3d4-e5f6-7890-abcd-ef1234567890'],
  }),
});

const data = await response.json();
console.log('Aktualisiert:', data.data);

Beispiel mit Python (vollständig)

python

import requests

headers = {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
}

guest_id = '880e8400-e29b-41d4-a716-446655440000'

payload = {
    'first_name': 'Elisabeth',
    'last_name': 'Schmidt-Müller',
    'email': 'elisabeth@example.com',
    'phone': '+49 171 9876543',
    'group': 'bride_family',
    'rsvp_status': 'confirmed',
    'menu_choice': 'vegetarian',
    'allergies': 'Laktose',
    'notes': 'Hat den Nachnamen geändert',
    'is_child': False,
    'age': None,
    'household_id': '770e8400-e29b-41d4-a716-446655440000',
    'tags': ['a1b2c3d4-e5f6-7890-abcd-ef1234567890'],
}

response = requests.put(
    f'https://hochzeitshelfer.app/api/v1/guests/{guest_id}',
    headers=headers,
    json=payload,
)

data = response.json()
print(f"Aktualisiert: {data['data']['first_name']} {data['data']['last_name']}")

Gast löschen

Löscht einen Gast unwiderruflich.

DELETE /api/v1/guests/{id}

Berechtigung: guests:write

Parameter

Parameter	Typ	Beschreibung
`id`	`string` (UUID)	ID des Gastes (Pfadparameter)

Beispiel-Request

bash

curl -X DELETE https://hochzeitshelfer.app/api/v1/guests/880e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"

Beispiel mit JavaScript

javascript

const guestId = '880e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://hochzeitshelfer.app/api/v1/guests/${guestId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
  },
});

// Erfolg: Status 204, kein Body
if (response.status === 204) {
  console.log('Gast erfolgreich gelöscht');
}

Beispiel mit Python

python

import requests

headers = {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
}

guest_id = '880e8400-e29b-41d4-a716-446655440000'

response = requests.delete(
    f'https://hochzeitshelfer.app/api/v1/guests/{guest_id}',
    headers=headers,
)

if response.status_code == 204:
    print('Gast erfolgreich gelöscht')

Antwort

Status: 204 No Content

Kein Response-Body bei erfolgreicher Löschung.

Praxisbeispiele

Alle zugesagten Gäste filtern (clientseitig)

Die API bietet derzeit keine serverseitige Filterung. Du kannst die Daten aber clientseitig filtern:

javascript

const response = await fetch('https://hochzeitshelfer.app/api/v1/guests', {
  headers: {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
  },
});

const { data: guests } = await response.json();

// Nur zugesagte Gäste
const confirmed = guests.filter(g => g.rsvp_status === 'confirmed');
console.log(`${confirmed.length} Zusagen`);

// Nur Kinder
const children = guests.filter(g => g.is_child);
console.log(`${children.length} Kinder`);

// Nur Gäste mit Allergien
const withAllergies = guests.filter(g => g.allergies);
console.log('Gäste mit Allergien:', withAllergies);

// Gäste nach Gruppe gruppieren
const byGroup = guests.reduce((acc, g) => {
  acc[g.group] = acc[g.group] || [];
  acc[g.group].push(g);
  return acc;
}, {});
console.log(byGroup);

// Gäste nach Haushalt gruppieren
const byHousehold = guests.reduce((acc, g) => {
  if (g.household_id) {
    acc[g.household_id] = acc[g.household_id] || [];
    acc[g.household_id].push(g);
  }
  return acc;
}, {});
console.log('Haushalte:', byHousehold);

// Menüwahl-Übersicht
const menuStats = guests.reduce((acc, g) => {
  const choice = g.menu_choice || 'nicht gewählt';
  acc[choice] = (acc[choice] || 0) + 1;
  return acc;
}, {});
console.log('Menüwahl:', menuStats);

Mehrere Gäste importieren

javascript

const guests = [
  {
    first_name: 'Thomas',
    last_name: 'Müller',
    email: 'thomas@example.com',
    group: 'bride_family',
    household_id: '770e8400-e29b-41d4-a716-446655440000',
  },
  {
    first_name: 'Sabine',
    last_name: 'Müller',
    email: 'sabine@example.com',
    group: 'bride_family',
    household_id: '770e8400-e29b-41d4-a716-446655440000',
  },
  {
    first_name: 'Lena',
    last_name: 'Müller',
    group: 'bride_family',
    is_child: true,
    age: 7,
    menu_choice: 'child',
    household_id: '770e8400-e29b-41d4-a716-446655440000',
  },
  {
    first_name: 'Sarah',
    last_name: 'Klein',
    email: 'sarah@example.com',
    group: 'friends_bride',
    rsvp_status: 'confirmed',
    menu_choice: 'vegan',
  },
];

for (const guest of guests) {
  const response = await fetch('https://hochzeitshelfer.app/api/v1/guests', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer DEIN_API_TOKEN',
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(guest),
  });

  if (response.ok) {
    const data = await response.json();
    console.log(`Erstellt: ${data.data.first_name} ${data.data.last_name || ''} (${data.data.id})`);
  } else {
    const error = await response.json();
    console.error(`Fehler bei ${guest.first_name}:`, error.errors);
  }
}

Gästeliste als CSV exportieren

python

import requests
import csv

headers = {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
}

response = requests.get(
    'https://hochzeitshelfer.app/api/v1/guests',
    headers=headers,
)
guests = response.json()['data']

with open('gaesteliste.csv', 'w', newline='', encoding='utf-8') as f:
    writer = csv.writer(f)
    writer.writerow([
        'Vorname', 'Nachname', 'E-Mail', 'Telefon',
        'Gruppe', 'RSVP', 'Menü', 'Allergien',
        'Kind', 'Alter', 'Haushalt-ID', 'Tags', 'Notizen',
    ])

    for guest in guests:
        writer.writerow([
            guest['first_name'],
            guest['last_name'] or '',
            guest['email'] or '',
            guest['phone'] or '',
            guest['group'],
            guest['rsvp_status'],
            guest['menu_choice'] or '',
            guest['allergies'] or '',
            'Ja' if guest['is_child'] else 'Nein',
            guest['age'] or '',
            guest['household_id'] or '',
            ', '.join(guest['tags']),
            guest['notes'] or '',
        ])

print(f'{len(guests)} Gäste exportiert nach gaesteliste.csv')

RSVP-Zusagen in Batch aktualisieren

python

import requests

headers = {
    'Authorization': 'Bearer DEIN_API_TOKEN',
    'Accept': 'application/json',
}

# Alle Gäste laden
response = requests.get(
    'https://hochzeitshelfer.app/api/v1/guests',
    headers=headers,
)
guests = response.json()['data']

# Alle ausstehenden Gäste auf "no_response" setzen
pending = [g for g in guests if g['rsvp_status'] == 'pending']

for guest in pending:
    response = requests.put(
        f"https://hochzeitshelfer.app/api/v1/guests/{guest['id']}",
        headers=headers,
        json={'rsvp_status': 'no_response'},
    )

    if response.ok:
        print(f"Aktualisiert: {guest['first_name']} {guest['last_name'] or ''}")
    else:
        print(f"Fehler bei {guest['first_name']}: {response.status_code}")

Gäste-API ​

Endpunkte ​

Gast-Objekt ​

Felder ​

Gruppen ​

RSVP-Status ​

Menüwahl ​

Alle Gäste auflisten ​

Beispiel-Request ​

Beispiel-Antwort ​

Einzelnen Gast abrufen ​

Parameter ​

Beispiel-Request ​

Beispiel-Antwort ​

Fehler ​

Neuen Gast erstellen ​

Request-Body — Alle verfügbaren Felder ​

Beispiel: Minimaler Request (nur Pflichtfelder) ​

Beispiel: Vollständiger Request (alle Felder) ​

Beispiel: Kind anlegen ​

Beispiel: Gast mit Haushalt anlegen ​

Beispiel: Gast mit Tags anlegen ​

Beispiel mit JavaScript (vollständig) ​

Beispiel mit Python (vollständig) ​

Beispiel mit PHP (vollständig) ​

Validierungsfehler ​

Gast aktualisieren ​

Parameter ​

Request-Body — Alle verfügbaren Felder ​

Beispiel: Einzelnes Feld ändern ​

Beispiel: RSVP-Zusage mit Menüwahl ​

Beispiel: Gast in einen Haushalt verschieben ​

Beispiel: Gast aus Haushalt entfernen ​

Beispiel: Tags aktualisieren ​

Beispiel: Kind-Status setzen ​

Beispiel: Vollständiges Update (alle Felder) ​

Beispiel: Feld auf null setzen ​

Beispiel mit JavaScript (vollständig) ​

Beispiel mit Python (vollständig) ​

Gast löschen ​

Parameter ​

Beispiel-Request ​

Beispiel mit JavaScript ​

Beispiel mit Python ​

Antwort ​

Praxisbeispiele ​

Alle zugesagten Gäste filtern (clientseitig) ​

Mehrere Gäste importieren ​

Gästeliste als CSV exportieren ​

RSVP-Zusagen in Batch aktualisieren ​

Gäste-API

Endpunkte

Gast-Objekt

Felder

Gruppen

RSVP-Status

Menüwahl

Alle Gäste auflisten

Beispiel-Request

Beispiel-Antwort

Einzelnen Gast abrufen

Parameter

Beispiel-Request

Beispiel-Antwort

Fehler

Neuen Gast erstellen

Request-Body — Alle verfügbaren Felder

Beispiel: Minimaler Request (nur Pflichtfelder)

Beispiel: Vollständiger Request (alle Felder)

Beispiel: Kind anlegen

Beispiel: Gast mit Haushalt anlegen

Beispiel: Gast mit Tags anlegen

Beispiel mit JavaScript (vollständig)

Beispiel mit Python (vollständig)

Beispiel mit PHP (vollständig)

Validierungsfehler

Gast aktualisieren

Parameter

Request-Body — Alle verfügbaren Felder

Beispiel: Einzelnes Feld ändern

Beispiel: RSVP-Zusage mit Menüwahl

Beispiel: Gast in einen Haushalt verschieben

Beispiel: Gast aus Haushalt entfernen

Beispiel: Tags aktualisieren

Beispiel: Kind-Status setzen

Beispiel: Vollständiges Update (alle Felder)

Beispiel: Feld auf null setzen

Beispiel mit JavaScript (vollständig)

Beispiel mit Python (vollständig)

Gast löschen

Parameter

Beispiel-Request

Beispiel mit JavaScript

Beispiel mit Python

Antwort

Praxisbeispiele

Alle zugesagten Gäste filtern (clientseitig)

Mehrere Gäste importieren

Gästeliste als CSV exportieren

RSVP-Zusagen in Batch aktualisieren