API-Zugang — Proyex programmatisch nutzen

Was ist der API-Zugang?

Die Proyex REST-API ermöglicht es dir, Proyex-Daten programmatisch zu lesen und zu bearbeiten. Nutze die API für eigene Integrationen, Automatisierungen oder um Proyex mit deinen bestehenden Tools zu verbinden.

Authentifizierung

Persönlicher API-Token

1. Gehe zu Profil > API.

2. Klicke auf Token erstellen.

3. Gib dem Token einen Namen (z. B. "Meine Integration").

4. Der Token wird einmalig angezeigt — kopiere ihn sofort, er kann nicht erneut eingesehen werden.

Verwende den Token als Bearer-Token in deinen API-Anfragen:

Authorization: Bearer dein-token

Token widerrufen

Du kannst einzelne Tokens jederzeit widerrufen. Der Token ist sofort ungültig und kann nicht wiederhergestellt werden.

Verfügbare Endpunkte

Die API bietet Zugriff auf alle wichtigen Bereiche von Proyex:

API-Format

Alle Anfragen und Antworten verwenden JSON. Basis-URL:

https://app.proyex.io/api/v1/

Erfolgreiche Antwort

Bei erfolgreichen Anfragen erhältst du ein JSON-Objekt mit den angeforderten Daten und einer Erfolgsmeldung.

Fehler

Bei Fehlern erhältst du einen Statuscode (z. B. 400, 403, 404, 422) mit einer Fehlerbeschreibung.

Listen filtern, sortieren und gruppieren

Listen-Endpunkte wie GET /api/v1/deals unterstützen mächtige Filter- und Sortier-Optionen, mit denen du große Datenmengen serverseitig einschränken kannst — perfekt für Reporting und Bulk-Reads.

Filter

Du kannst nach Status, Datum, UTM-Parametern oder eigenen Custom Fields filtern. Beispiele für /api/v1/deals:

• ?status=won — nur gewonnene Deals (auch open, lost, archived, all)

• ?closed_at_from=2026-01-01&closed_at_to=2026-03-31 — Zeitraum-Filter auf das Abschlussdatum

• ?utm_source=ig&utm_campaign=spring-2026 — Filter auf UTM-Spalten (auch utm_medium, utm_term, utm_content)

• ?custom_fields[offer_value][gte]=5000 — Filter auf Custom-Field-Werte (Operatoren: eq, gte, lte, contains)

Sortierung

Nutze ?sort=feld für aufsteigend oder ?sort=-feld für absteigend. Default ist -updated_at (neueste zuerst). NULL-Werte (z. B. closed_at bei offenen Deals) landen automatisch am Ende, unabhängig von der Richtung.

Beziehungen mitladen (?include=)

Statt mehrerer Folge-Anfragen lädst du Beziehungen direkt mit. Komma-getrennt, mit Whitelist:

• contact, owner, projects, activities, custom_fields, creator

• contact_attribution — die UTM-Werte des verknüpften Kontakts als First-Touch, ergänzend zu den UTM-Werten am Deal selbst (Last-Touch)

Unbekannte Include-Werte werden mit Status 422 abgelehnt.

Pagination behält Filter

Die Pagination-Links in meta.links[].url enthalten alle aktiven Filter und Sort-Parameter. Du kannst Pagination-Links direkt folgen, ohne Query-Parameter manuell zu rekonstruieren.

Aggregate / Reporting

Für Auswertungen ohne komplette Daten-Downloads nutze GET /api/v1/deals/stats:

/api/v1/deals/stats?group_by=utm_source&since=2026-01-01&until=2026-03-31&status=won

Liefert count, sum_value und avg_value pro Gruppe. Gruppieren kannst du nach utm_source, utm_medium, utm_campaign, stage_id, owner_id oder pipeline_id.

Aktivitäten paginiert

Im Deal-Detail liefern wir die 20 neuesten Aktivitäten direkt mit. Für die volle Liste nutze den Sub-Endpunkt: GET /api/v1/deals/{id}/activities (paginiert, Default 20, Maximum 100 pro Seite).

Listen nach Datum filtern

Bei den CRM-Listen-Endpunkten — Deals, Kontakte, Unternehmen, Aktivitäten und Leads — kannst du Ergebnisse zusätzlich zum Sortieren auch nach Erstellungs- und Änderungsdatum filtern. So rufst du z. B. gezielt nur kürzlich aktualisierte Datensätze ab.

Folgende optionale Query-Parameter stehen zur Verfügung (Datum im ISO-Format, z. B. 2026-01-31):

• created_after — nur am oder nach diesem Datum erstellte Objekte
• created_before — nur am oder vor diesem Datum erstellte Objekte
• updated_after — nur am oder nach diesem Datum zuletzt geänderte Objekte
• updated_before — nur am oder vor diesem Datum zuletzt geänderte Objekte

Beispiel — alle Deals, die seit Jahresbeginn aktualisiert wurden:

GET /api/v1/deals?teamId=1&updated_after=2026-01-01

Die Parameter lassen sich kombinieren, um einen Zeitraum einzugrenzen. Ein ungültiges Datum ergibt eine Fehlermeldung (Status 422).

Rate Limiting

Die API ist auf eine bestimmte Anzahl von Anfragen pro Minute begrenzt. Wenn du das Limit überschreitest, erhältst du eine Fehlermeldung (Status 429). Warte kurz und versuche es erneut.

Berechtigungen

API-Tokens haben die gleichen Berechtigungen wie der Nutzer, der sie erstellt hat. Du kannst nur auf Daten zugreifen, auf die du auch über die Web-Oberfläche Zugriff hast.

Häufige Fragen

Kann ich mehrere Tokens erstellen?

Ja, du kannst beliebig viele Tokens erstellen — z. B. einen pro Integration oder pro Dienst.

Was passiert, wenn ich meinen Token verliere?

Du kannst den alten Token widerrufen und einen neuen erstellen. Der verlorene Token funktioniert danach nicht mehr.

Gibt es eine API-Dokumentation?

Ja, die API ist vollständig dokumentiert. Die Dokumentation findest du unter deiner Proyex-URL im API-Bereich.

Tipps & Hinweise

• Erstelle separate Tokens für jede Integration — so kannst du einzelne Verbindungen widerrufen, ohne andere zu beeinträchtigen.

• Nutze die API in Kombination mit Webhooks für leistungsstarke Zwei-Wege-Integrationen.

• Beachte das Rate Limiting bei automatisierten Anfragen und baue Wartezeiten ein.