Zum Inhalt springen
NeuSo funktioniert es

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.

Tutorials
Entwickler & CLI
Min. Lesezeit
9 min
Schritte
7 · Experte

  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. 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. 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. 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": "[email protected]", "first_name": "Jane", "company_name": "Acme" }'

  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. 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. 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

  • 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.

  • 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.

  • 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.

  • 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.

Entwickler & CLI

Akquise, die weiterläuft, wenn du offline bist.Leads, E-Mails, Follow-ups und Antworten, erledigt.

Verbinde unbegrenzte Postfächer und lass KI-Agenten Leads finden, jede E-Mail schreiben und nachfassen. Oder sende deine eigenen Vorlagen im manuellen Modus. Ab $29/Monat.

Starte deine $1-Testphase Preise ansehen

$1 für 3 Tage · Jederzeit kündbar · Kein Vertrag

Mit KI installieren

Dein Coding-Agent richtet die FirstSales CLI und Skills für dich ein.

Prompt für Claude Code

I'm setting up FirstSales (https://firstsales.io), an AI outbound sales platform: campaigns, contacts, a reply inbox, deliverability and lead signals. Help me get my workspace sending real, good emails end to end, from Claude Code.

Read these first so you know how FirstSales works:
- Developer docs and API: https://developer.firstsales.io
- CLI: https://www.npmjs.com/package/@firstsales.io/cli
- Skills for coding agents: https://github.com/firstsalesio/firstsales-skills (read README.md and GUIDE.md)

Setup
1. Install the CLI: npm install -g @firstsales.io/cli
2. Install the FirstSales skills:
   claude plugin marketplace add firstsalesio/firstsales-skills
   claude plugin install firstsales@firstsales
3. Ask me if I already have a FirstSales account. If not, send me to https://app.firstsales.io to sign up.
4. Ask me to create an API key under Settings → API → API Keys, with only the scopes we need.
   Never ask me to paste the key into this chat. Tell me to run this in my own terminal, so the key stays hidden:
   read -rs FS_KEY && firstsales auth login --api-key "$FS_KEY"; unset FS_KEY
5. Run `firstsales whoami` and tell me which workspace and organisation we are connected to.

Then ask me about my business: what I sell, who I sell to (roles, company size, countries), my best customers, and what I use today for outbound (tools, lists, mailboxes). Walk me through:
1. Teaching FirstSales my business: website, offer, proof points and case studies in the knowledge base, so the AI writes like someone who knows the product.
2. Connecting my sending mailboxes and checking my sending domain: SPF, DKIM, DMARC and warm-up. If anything is unhealthy, tell me the exact DNS record to add.
3. Bringing in contacts: import my CSV or CRM export into a clean list, remove duplicates and bad emails, and block domains I must never email (customers, competitors, my own).
4. Building my first campaign: the right list, senders, steps and timing. Write the sequence with me, show me the drafts, and do not launch until I say yes.
5. Setting up Signals if it fits: find people engaging with LinkedIn posts about topics my buyers care about, and turn them into leads.
6. Inviting my team and giving each person the right access.

Once campaigns run, show me how to work the reply inbox from here: which replies need an answer, draft responses in my voice, and move good conversations into deals. If I use Cal.com, connect it so follow-ups can offer my booking link (not the first email).

Throughout, as you learn about my business, proactively suggest and help create:
- Reply templates for the questions and objections my prospects are likely to raise, based on my product, site and codebase if you can see them.
- Campaign ideas and segments worth testing, with the reason for each.

Safety rules:
- Show every change as a dry run (--dry-run) first and wait for my yes. Never send emails, launch campaigns or delete anything without my yes.
- Tell me before anything that spends credits, and how many.

Be opinionated. If the docs give a sensible default, just use it. Don't make me choose between five options.
Developer docs ↗npm: @firstsales.io/cli ↗GitHub: firstsales-skills ↗