API-Referenz

Fynex stellt eine REST-API für den programmatischen Zugriff bereit. Alle Endpoints erfordern Authentifizierung über ein Supabase-JWT-Token im Header Authorization: Bearer <token>.

Basis-URL:

• Entwicklung: http://localhost:3001
• Produktion: https://api.fynex.solutions

Dispatch

E-Mail senden

POST /api/dispatch/email

Parameter	Typ	Erforderlich	Beschreibung
account_id	UUID	Ja	Zielkonto
template_id	UUID	Nein	Zu verwendende Message-Template
action_type	string	Nein	Action-Typ (Standard: reminder)

Responses: 200 E-Mail gesendet, 401 Unauthorized, 422 Dispatch blockiert.

SMS senden

POST /api/dispatch/sms

Parameter	Typ	Erforderlich	Beschreibung
account_id	UUID	Ja	Zielkonto
template_id	UUID	Nein	Zu verwendende Message-Template
action_type	string	Nein	Action-Typ (Standard: reminder)

Responses: 200 SMS gesendet, 422 Dispatch blockiert.

WhatsApp senden

POST /api/dispatch/whatsapp

Parameter	Typ	Erforderlich	Beschreibung
account_id	UUID	Ja	Zielkonto
template_id	UUID	Nein	Zu verwendende Message-Template
action_type	string	Nein	Action-Typ (Standard: reminder)

Responses: 200 WhatsApp-Nachricht gesendet, 422 Dispatch blockiert.

Voice-Call starten

POST /api/dispatch/voice

Parameter	Typ	Erforderlich	Beschreibung
account_id	UUID	Ja	Zielkonto
agent_type	string	Nein	ai (Standard) oder human
supervisor_user_id	UUID	Nein	User-ID für überwachte Calls
voice_opening_mode	string	Nein	Nur AI: inherit (Standard), callee_first oder agent_first. Wird ignoriert, wenn agent_type human ist.

Responses: 200 Call gestartet (enthält call_sid und conversation_id), 422 Dispatch blockiert, 502 Provider-Fehler.

Dispatch-Validierung

Alle Dispatch-Endpoints setzen diese Regeln vor dem Versand durch:

• Opt-out — Blockiert, wenn der Kontakt abgemeldet ist.
• Frequency limits — Blockiert, wenn die maximale Anzahl Kontakte pro Tag/Woche überschritten würde.
• Allowed hours — Blockiert außerhalb der konfigurierten Kontaktzeiten der Organisation.
• Account paused — Blockiert, wenn der Account-Status paused ist.

Bei Blockierung enthält die Response { "blocked": true, "error": "reason" }.

Admin

Telefonnummern

POST /api/admin/phone-numbers

Parameter	Typ	Erforderlich	Beschreibung
action	string	Ja	search, buy oder release
country	string	Nein	Ländercode für Suche
areaCode	string	Nein	Vorwahl für Suche
phoneNumber	string	Nein	Nummer zum Kaufen oder Freigeben
organizationId	UUID	Nein	Zuzuweisende Organisation
channelConfigId	UUID	Nein	Zu aktualisierende Channel-Config

E-Mail-Domains

POST /api/admin/email-domains

Parameter	Typ	Erforderlich	Beschreibung
action	string	Ja	create oder verify
domain	string	Nein	Domain-Name
organizationId	UUID	Nein	Organisation
channelConfigId	UUID	Nein	Channel-Config

ElevenLabs Agent

POST /api/admin/elevenlabs-agent

Parameter	Typ	Erforderlich	Beschreibung
action	string	Ja	provision, status oder set_agent_id
organizationId	UUID	Nein	Organisation (meist aus Auth abgeleitet)
agent_id	string	Bei set_agent_id	ElevenLabs Agent-ID für den Voice-Kanal

provision legt den ConvAI-Agenten an bzw. aktualisiert ihn und registriert bei konfigurierter Twilio-Nummer ohne bestehende ElevenLabs-Telefon-ID die Nummer automatisch bei ElevenLabs. Die Antwort kann phone_number_id enthalten.

set_agent_id ist für Organisationen mit eigenverwalteten Zugangsdaten und eigenem Agent gedacht.

Sprach-Konfiguration (Voice)

GET /api/admin/voice-config
PATCH /api/admin/voice-config

GET liefert aktuelle Defaults: llm, voice_id, voices (Sprach-Mapping), voice_opening_mode, agent_id, org_language, supported_llms, curated_voices.

PATCH aktualisiert Organisation und Voice-Kanal in einem Request. Mindestens ein Feld senden:

Feld	Typ	Beschreibung
llm	string	LLM-ID für Conversational AI (gegen unterstützte Liste validiert)
voice_id	string	Standard-ElevenLabs-Stimme für die Hauptsprache der Org
voices	object	Map Sprachcode → ElevenLabs-Stimmen-ID
voice_opening_mode	string	callee_first oder agent_first
agent_id	string	ElevenLabs Agent-ID (z. B. Eigenverwaltung)

Campaigns

Campaign anlegen

POST /api/admin/campaigns

Parameter	Typ	Erforderlich	Beschreibung
name	string	Ja	Campaign-Name (1–200 Zeichen)
objective	string	Nein	Campaign-Ziel (max. 1000 Zeichen)
strategy_id	UUID	Nein	Zuzuweisende Strategy (erforderlich zum Aktivieren)
status	string	Nein	Initialer Status (Standard: draft)
start_date	string	Nein	Startdatum (YYYY-MM-DD)
end_date	string	Nein	Enddatum (YYYY-MM-DD, muss ≥ Start sein)

Responses: 201 Campaign erstellt, 422 Validierung fehlgeschlagen (ungültige Daten, fehlende Strategy bei aktivem Status).

Campaign aktualisieren

PATCH /api/admin/campaigns/:id

Akzeptiert dieselben Felder wie beim Anlegen. Status-Übergänge werden validiert:

• draft → active (erfordert strategy_id)
• active → paused (leert ausstehende Queue-Items)
• active → completed
• paused → active, paused → completed

Responses: 200 Campaign aktualisiert, 422 Ungültiger Status-Übergang oder Validierungsfehler.

Campaign löschen

DELETE /api/admin/campaigns/:id

Entfernt die Campaign. Allen zugewiesenen Accounts wird campaign_id auf null gesetzt. Ausstehende Queue-Items für diese Campaign werden abgebrochen.

Responses: 200 Campaign gelöscht.

Campaign-Summary

GET /api/admin/campaigns/:id/summary

Liefert berechnete Campaign-Metriken:

Feld	Typ	Beschreibung
campaign	object	Campaign-Details (id, name, status, dates)
account_count	number	Gesamtzahl zugewiesener Accounts
contacted_count	number	Accounts mit mindestens einer Interaction
promise_count	number	Zahlungszusagen von Campaign-Accounts
total_recovered	number	Summe der Zahlungen von Campaign-Accounts
contact_rate	number	contacted_count / account_count (0,0 bis 1,0)

Responses: 200 Summary-Daten.

Execution Engine

Execution pausieren

POST /api/admin/execution/pause

Pausiert den automatischen Dispatch für Ihre Organisation. Queue-Items bleiben bestehen, werden aber nicht verarbeitet.

Responses: 200 Execution pausiert.

Execution fortsetzen

POST /api/admin/execution/resume

Setzt die automatische Dispatch-Verarbeitung fort.

Responses: 200 Execution fortgesetzt.

Queue-Status abrufen

GET /api/admin/execution/status

Liefert Anzahlen ausstehender, verarbeitender, abgeschlossener, fehlgeschlagener und übersprungener Items für heute sowie das Pausen-Flag.

Accounts enqueuen

POST /api/admin/execution/enqueue

Parameter	Typ	Erforderlich	Beschreibung
campaign_id	UUID	Nein	Auf eine Campaign begrenzen

Löst manuell die Account-Bewertung und das Enqueuing aus. Berechtigte Accounts werden in die Execution-Queue aufgenommen. Wenn campaign_id angegeben ist, muss die Campaign active sein und im Datumsbereich liegen.

Responses: 200 Liefert { enqueued: <count> }, 422 Campaign nicht aktiv oder außerhalb des Datumsbereichs.

Bulk Operations

Bulk Account Actions

POST /api/admin/bulk/accounts

Parameter	Typ	Erforderlich	Beschreibung
account_ids	UUID[]	Ja	Zu ändernde Accounts (max. 500)
action	string	Ja	pause, resume, assign_campaign, assign_strategy, change_status
campaign_id	UUID	Nein	Erforderlich für assign_campaign
strategy_id	UUID	Nein	Erforderlich für assign_strategy
status	string	Nein	Erforderlich für change_status

Responses: 200 Liefert { affected: <count> }.

Billing

Checkout Session erstellen

POST /api/billing/checkout

Parameter	Typ	Erforderlich	Beschreibung
price_id	string	Ja	Stripe Price ID
success_url	URL	Ja	Redirect-URL nach Zahlung
cancel_url	URL	Ja	Redirect-URL bei Abbruch

Responses: 200 Liefert { url: "https://checkout.stripe.com/..." }, 503 Billing nicht konfiguriert.

Billing Portal

POST /api/billing/portal

Parameter	Typ	Erforderlich	Beschreibung
return_url	URL	Ja	Redirect-URL nach Portal

Responses: 200 Liefert { url: "https://billing.stripe.com/..." }, 503 Billing nicht konfiguriert.

Notifications

Notifications auflisten

GET /api/notifications

Liefert alle Notifications für den authentifizierten Benutzer, sortiert nach neuesten zuerst.

Notification als gelesen markieren

PATCH /api/notifications/:id/read

Markiert eine einzelne Notification als gelesen.

Alle als gelesen markieren

POST /api/notifications/mark-all-read

Markiert alle ungelesenen Notifications für den authentifizierten Benutzer als gelesen.

Voice

Signed URL abrufen

POST /api/voice/signed-url

Liefert eine signierte WebSocket-URL für browserbasierte Voice-Sessions.

Parameter	Typ	Erforderlich	Beschreibung
organization_id	UUID	Ja	Organisation

Response: { "signedUrl": "wss://..." }

Capabilities prüfen

POST /api/voice/capabilities

Prüft, ob eine Organisation Voice-Calls tätigen kann (Twilio-Credentials, ElevenLabs-Agent, Telefonnummer).

Parameter	Typ	Erforderlich	Beschreibung
organization_id	UUID	Ja	Organisation

Interactions

Voice-Transcript wiederherstellen

POST /api/interactions/:id/refresh-voice

Holt die Conversation-Daten von ElevenLabs für eine Voice-Interaction, deren Post-Call-Webhook verpasst wurde. Aktualisiert Transcript, Disposition, Contact Result, Sentiment und alle Analyse-Metadaten. Wenn der Strategy-Step in waiting_response stecken blieb, wird er automatisch freigegeben.

Dieser Endpoint ist idempotent — ein erneuter Aufruf für eine Interaction, die bereits ein Transcript hat, überschreibt es mit den neuesten Daten von ElevenLabs.

Parameter	Typ	Ort	Erforderlich	Beschreibung
id	UUID	path	Ja	Interaction ID

Responses:

Code	Beschreibung
200	Transcript wiederhergestellt; liefert aktualisierte Interaction
404	Interaction nicht gefunden oder falsche Organisation
422	Keine Voice-Interaction, keine Conversation-ID oder Call noch aktiv
502	Abruf der ElevenLabs-API fehlgeschlagen

Public API v1

Die v1-API ermöglicht programmatischen Zugriff für die Integration externer Systeme. Authentifizierung über Header X-API-Key oder Bearer-JWT.

Authentifizierung

Method	Header	Anwendungsfall
API Key	X-API-Key: fynex_pk_...	Machine-to-machine-Integrationen
JWT	Authorization: Bearer <token>	Browserbasierter Zugriff

Accounts

POST /api/v1/accounts

Legt einen Account an oder führt Upsert durch. Wenn external_id angegeben ist und einem bestehenden Account entspricht, wird dieser aktualisiert.

Parameter	Typ	Erforderlich	Beschreibung
external_id	string	Nein	Eindeutige ID Ihres Systems für diesen Account
source_system	string	Nein	Bezeichnung des Quellsystems
contact	object	Ja	Kontaktdaten (Name erforderlich, E-Mail/Telefon/WhatsApp optional)
total_amount	number	Ja	Gesamtforderungsbetrag
pending_balance	number	Nein	Standard: total_amount
reference	string	Nein	Menschenlesbare Referenznummer
currency	string	Nein	ISO-4217-Code (Standard: ARS)

GET /api/v1/accounts

Listet Accounts mit Pagination.

Parameter	Typ	Erforderlich	Beschreibung
limit	number	Nein	Max. Ergebnisse (Standard 50, max. 1000)
offset	number	Nein	Erste N Ergebnisse überspringen
status	string	Nein	Filter nach collection_status
external_id	string	Nein	Filter nach external_id

GET /api/v1/accounts/:id

Ruft einen Account anhand der Fynex-ID ab. Mit ?by=external_id erfolgt die Suche per external ID.

PATCH /api/v1/accounts/:id

Aktualisiert Account-Felder.

Contacts

POST /api/v1/contacts
GET /api/v1/contacts
GET /api/v1/contacts/:id
PATCH /api/v1/contacts/:id

Gleiches Muster wie bei Accounts. Unterstützt Upsert per external_id.

Payments

POST /api/v1/payments

Registriert eine externe Zahlung. Übergeben Sie account_id oder account_external_id.

Import & Export

POST /api/v1/import

Startet asynchronen Bulk-Import. Liefert { job_id, status }.

GET /api/v1/import/:jobId

Prüft den Fortschritt des Import-Jobs.

POST /api/v1/export/accounts

Exportiert Accounts als JSON oder CSV mit Filtern.

Webhook Subscriptions

POST /api/v1/webhooks
GET /api/v1/webhooks
PATCH /api/v1/webhooks/:id
DELETE /api/v1/webhooks/:id
POST /api/v1/webhooks/:id/test

Verwaltet ausgehende Webhook-Subscriptions.

Rate Limits

Alle v1-Endpoints: 100 Requests pro 15 Minuten pro API-Key.

Webhooks

Diese Endpoints empfangen Callbacks von externen Providern. Sie werden nicht von Client-Anwendungen aufgerufen.

Endpoint	Provider	Validierung
POST /api/webhooks/twilio	Twilio	HMAC-SHA1-Signatur
POST /api/webhooks/resend	Resend	Svix HMAC-SHA256
POST /api/webhooks/elevenlabs	ElevenLabs	HMAC-SHA256
POST /api/webhooks/agent-tool-handler	ElevenLabs	HMAC-SHA256
POST /api/webhooks/stripe	Stripe	Stripe-Signatur

System

Health Check

GET /health

Liefert { "status": "ok", "timestamp": "..." }, wenn der Server läuft.