Sales Mentor

API-Dokumentation

Über die öffentliche API verbindet ein Team seine eigenen Systeme mit Sales Mentor: Ein Dialer schickt fertige Gespräche zur Analyse, ein CRM oder ein Zapier-Ablauf legt Kontakte und Deals an. JSON hinein, JSON heraus, UTF-8.

Basis-URL: https://www.sales-mentor.ai/api/v1

Authentifizierung

Inhaber und Manager legen API-Schlüssel im Cockpit an, auf der Seite Team unter API-Schlüssel. Ein Schlüssel wird nur einmal angezeigt; leg ihn in deinem Passwort- oder Secret-Manager ab. Er geht als Bearer-Token mit:

Authorization: Bearer rz_live_...

Schlüssel haben Rechte: read (Listen und Details) und write (anlegen und ändern). Ein Schlüssel handelt für sein Team und legt Einträge im Namen der Person an, die ihn erstellt hat; er sieht nie mehr, als diese Person im Cockpit sehen würde. Widerrufene Schlüssel bekommen 401.

Fehler

{"detail": {"error": "<code>", "message": "<kurzer Text>"}}

Entscheide nach detail.error, dem festen Code; detail.message ist ein kurzer englischer Satz fürs Log. Manche Ablehnungen tragen einen weiteren Schlüssel in detail: ein 409 bei einem Duplikat existing_id, ein 422 zu einem Feld field. Ein Body, der sich nicht lesen lässt (kaputtes JSON, ein Feld vom falschen Typ), bekommt stattdessen das übliche 422, bei dem detail eine Liste mit einem Eintrag je Problem ist.

POST /calls antwortet außerdem mit 402 subscription_required (die Person, der der Schlüssel gehört, darf das kostenpflichtige Produkt nicht nutzen) und 428 consent_required (sie hat den Datenschutzhinweis in der App noch nicht angenommen).

Endpunkte

GET /me
Team, Rolle und Pipeline-Stufen des Schlüssels.
GET /contacts?q=&cursor=&limit=
Liste, seitenweise: items, next_cursor, total.
POST /contacts
Finden oder anlegen über email; 201 angelegt, 200 aktualisiert.
GET /contacts/{id}
Der Kontakt mit Firma, Deals, Aufgaben und Verlauf.
GET /companies?q=
Liste.
POST /companies
Finden oder anlegen über name.
GET /deals?q=&status=&stage=
Liste; status ist open, won, lost oder all.
POST /deals
Anlegen: value_eur (eine Zahl oder Text wie "15.000" oder "15k") oder value_cents, stage als Schlüssel der Stufe, contact_id, company oder company_id, next_step, next_step_at.
GET /deals/{id}
Der Deal mit Aufgaben, Verlauf und Phasenwechseln.
PATCH /deals/{id}
Felder eines offenen Deals ändern; value_eur wie beim Anlegen.
POST /activities
kind note, call, email, meeting oder whatsapp; body; verknüpft über deal_id, contact_id, company_id oder contact_email.
POST /tasks
title, due_at, deal_id, contact_id.
POST /calls
Ein Transkript schicken: transcript, filename, deal_id, contact_id oder contact_email, language de oder en. Antwort 202; die Analyse läuft im Hintergrund.
GET /calls/{id}
Stand und Ergebnis einer Analyse.

Jeder Eintrag kommt in derselben Form, egal welcher Endpunkt ihn liefert.

Beispiel: Ein Dialer schickt ein fertiges Gespräch

curl -X POST https://www.sales-mentor.ai/api/v1/calls \
  -H "Authorization: Bearer rz_live_..." \
  -H "Content-Type: application/json" \
  -d '{"transcript": "...", "filename": "aircall-4711", "contact_email": "eva@huber.example"}'

Die Analyse landet im Verlauf des Kontakts (und des Deals, wenn der Kontakt mit einem verknüpft ist), und der Webhook call_analysis.done wird ausgelöst. Das Ergebnis enthält scores (fünf Dimensionen, 1 bis 5), strongest_moment, biggest_miss (mit what_to_say_instead), drei moments und ein commitment. biggest_miss und jeder Moment können method tragen: den Namen der Coaching-Methode, die die Analyse angewendet hat, nur wenn sie eine genannt hat. Mit language en sind die Coaching-Texte (why, coaching, commitment) englisch und method kommt mit einem englischen method_label; what_to_say_instead bleibt in der Sprache des Gesprächs und in der Anrede, die der Verkäufer benutzt hat, denn es ist ein Satz für den Kunden.

Webhooks

Inhaber und Manager tragen Webhooks im Cockpit ein, auf der Seite Team unter Webhooks (URL und Ereignisse). Jede Zustellung ist ein POST mit:

Content-Type: application/json
X-RZ-Event: deal.created
X-RZ-Delivery: <id>
X-RZ-Signature: sha256=<hex HMAC-SHA256 des rohen Bodys mit dem Webhook-Secret>

Der Body ist {"id", "event", "created_at", "data"}, wobei data der Eintrag ist, wie die API ihn liefert. Ereignisse:

Antworte innerhalb von 10 Sekunden mit 2xx; alles andere wird mit wachsendem Abstand erneut zugestellt, insgesamt 5 Versuche. Prüf die Signatur, bevor du einem Body vertraust. Angenommen werden nur https-URLs und keine Ziele in privaten Netzen.