NeuSo funktioniert es
FirstSales
Startseite/Tutorials/FirstSales API-Schnellstart
Entwickler & CLI

FirstSales API-Schnellstart

Erzeugen Sie einen API-Schlüssel und tätigen Sie Ihre ersten Aufrufe — erstellen Sie Kontakte, tragen Sie sie in Kampagnen ein und rufen Sie Antworten aus dem Posteingang über die REST-API ab.

9 Min. Lesezeit·Experte·7 Schritte
  1. 1

    Einen Developer API Key erzeugen

    Gehen Sie in der App zu Settings → API und erstellen Sie einen Developer API Key. Legen Sie Scopes und Zugriffsstufe (read vs. read-write) auf das Minimum fest, das die Integration benötigt. Das Secret wird einmalig angezeigt — kopieren Sie es sofort in einen Secret-Manager; die App speichert nur eine geschwärzte Form.

    Widerrufen und neu erzeugen Sie auf derselben Seite, falls ein Key jemals durchsickert.

  2. 2

    Identität mit whoami prüfen

    Die Basis-URL lautet https://api.app.firstsales.io. Die Authentifizierung erfolgt über ein Bearer-Token. Beginnen Sie immer damit, zu bestätigen, dass der Key zur erwarteten Org und zum erwarteten Workspace auflöst — GET /api/v1/whoami:

    curl https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  3. 3

    Ihre Org- und Workspace-IDs finden

    Jede Ressource ist einer Organisation und einem Workspace zugeordnet, sodass die meisten Pfade wie /api/v1/organizations/{orgId}/workspaces/{workspaceId}/… aussehen. Listen Sie sie auf:

    # Organizations you can access
curl https://api.app.firstsales.io/api/v1/organizations \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

# Workspaces inside an org
curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  4. 4

    Einen Kontakt (idempotent) erstellen

    Senden Sie einen Kontakt per POST an einen Workspace. Übergeben Sie einen Idempotency-Key-Header, damit eine wiederholte Anfrage nie ein Duplikat erzeugt — sicher bei einem Replay nach einem Netzwerkfehler.

    curl -X POST \
  https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: jane-acme-2026-01" \
  -d '{ "email": "jane@acme.com", "first_name": "Jane", "company_name": "Acme" }'
  5. 5

    Kampagnen-Analysen auslesen

    Rufen Sie Funnel- und Engagement-Metriken für eine Kampagne ab, um Ergebnisse in Ihr eigenes Reporting zu synchronisieren — ohne das Dashboard zu scrapen:

    curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/campaigns/CAMPAIGN_ID/analytics \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  6. 6

    Antworten aus dem Inbox auslesen

    Listen Sie Inbox-Threads auf, um Sendungen, Öffnungen, Antworten und Bounces in Ihre Systeme zu übernehmen. Thread-Inhalte sind in der Listenansicht geschwärzt; rufen Sie einen einzelnen Thread für Details ab. So leiten Sie positive Antworten in ein CRM, solange native Connectors noch nicht verfügbar sind.

    curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/inbox/threads \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  7. 7

    Innerhalb der öffentlichen Oberfläche bleiben

    Die API stellt ausschließlich die öffentliche /api/v1-Oberfläche bereit. Rufen Sie keine app-privaten Routen, Provider-Callbacks, Tracking-Pixel, Abmelde-Handler oder internen Cron-Routen auf — sie sind nicht Teil des Vertrags und werden brechen. Liefert ein Aufruf unsupported_operation, stoppen Sie und behandeln Sie dies als „nicht über die API verfügbar", nicht als etwas, das man umgehen sollte.

    Standard-Statuscodes gelten: 401 falscher/widerrufener Key, 422 Validierung (Body nennt das Feld), 429 Rate-Limit erreicht (zurückhalten und erneut versuchen).

Profi-Tipps

Hart erarbeitete Abkürzungen, damit die Aufwärmung auf Kurs bleibt.

1

Erst whoami, dann schreiben

Bestätigen Sie, dass der Key zur gewünschten Org/zum gewünschten Workspace auflöst, bevor Sie einen verändernden Aufruf tätigen. Ein Key mit falschem Workspace-Scope ist die häufigste Ursache dafür, Daten am falschen Ort zu schreiben.

2

Bei Create-Aufrufen immer einen Idempotency-Key senden

Netzwerk-Retries passieren. Ein Idempotency-Key macht einen wiederholten POST zu einem No-op statt zu einem doppelten Kontakt oder einer doppelten Abbuchung.

3

Den Key einmal speichern, nie ausgeben

Das Secret wird nur einmalig angezeigt und geschwärzt gespeichert. Geben Sie es direkt in einen Secret-Manager ein; loggen, committen oder in einem Client-Bundle ausliefern Sie es nie.

4

unsupported_operation als harten Stopp behandeln

Gibt die API unsupported_operation zurück, ist das Gewünschte nicht im öffentlichen Vertrag enthalten. Greifen Sie nicht auf app-private Routen zurück, um es zu erzwingen — melden Sie stattdessen die Einschränkung.

Häufig gestellte Fragen

Wo bekomme ich einen API Key?

Settings → API. Erstellen Sie einen Developer API Key mit den benötigten Scopes und der benötigten Zugriffsstufe; er wird einmalig angezeigt, also kopieren Sie ihn sofort. Widerrufen und neu erzeugen Sie auf derselben Seite, falls er offengelegt wird.

Wie lauten Basis-URL und Authentifizierung?

Basis-URL https://api.app.firstsales.io; authentifizieren Sie sich mit Authorization: Bearer $FIRSTSALES_API_KEY und senden Sie JSON. Beginnen Sie mit GET /api/v1/whoami, um den Kontext zu bestätigen.

Warum sind die Pfade so lang?

Ressourcen sind einer Org und einem Workspace zugeordnet, sodass Pfade wie /api/v1/organizations/{orgId}/workspaces/{workspaceId}/… aussehen. Holen Sie die IDs über /api/v1/organizations und dessen /workspaces-Unterressource (oder aus whoami).

Wie vermeide ich doppelte Schreibvorgänge?

Senden Sie einen Idempotency-Key-Header bei Create-Anfragen. Eine wiederholte Anfrage mit demselben Key liefert das ursprüngliche Ergebnis zurück, statt einen zweiten Datensatz zu erzeugen — sicher bei einem Replay nach einem Timeout.

Kann ich Kampagnenmetriken und Antworten auslesen?

Ja — GET …/campaigns/{id}/analytics für Funnel/Engagement und GET …/inbox/threads für Konversationsaktivität. Thread-Inhalte sind in der Liste geschwärzt; rufen Sie einen einzelnen Thread für vollständige Details ab.

Gibt es stattdessen eine Zapier- oder CRM-Integration?

Kein Zapier-Connector, und native CRM-Connectors (Salesforce, HubSpot, Pipedrive) sind noch nicht verfügbar. Bis diese kommen, ist die REST-API — oder die CLI — der unterstützte Weg zur Integration und Synchronisierung.

Was bedeutet unsupported_operation?

Die angeforderte Aktion ist nicht Teil des öffentlichen /api/v1-Vertrags. Stoppen Sie und melden Sie dies — rufen Sie keine app-privaten Routen, Callbacks, Pixel oder internen Endpunkte auf, um es zu umgehen; diese werden nicht unterstützt und brechen.

Bereit, das in die Praxis umzusetzen?

Starten Sie Ihre FirstSales-Testphase und richten Sie in wenigen Minuten ein aufgewärmtes, authentifiziertes Postfach ein.

Für 1 $ starten
Alle Tutorials