Sales Mentor

API documentation

With the public API a team connects its own systems to Sales Mentor: a dialer pushes finished calls for analysis, a CRM or a Zapier flow creates contacts and deals. JSON in, JSON out, UTF-8.

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

Authentication

Owners and managers create API keys in the cockpit, on the Team page under API keys. A key is shown once; store it in your secret manager. Send it as a bearer token:

Authorization: Bearer rz_live_...

Keys have scopes: read (lists and details) and write (create and change). A key acts for its team and writes rows owned by the person who created it; it never sees more than that person would in the cockpit. Revoked keys answer 401.

Errors

{"detail": {"error": "<code>", "message": "<short text>"}}

Branch on detail.error, the stable code; detail.message is a short English sentence for a log. Some refusals carry one more key in detail: a 409 duplicate existing_id, a 422 on one field field. A body that cannot be parsed (malformed JSON, a field of the wrong type) gets the standard 422 instead, where detail is a list with one entry per problem.

POST /calls also answers 402 subscription_required (the key owner may not use the paid product) and 428 consent_required (the key owner has not accepted the privacy notice in the app).

Endpoints

GET /me
Team, role and pipeline stages of the key.
GET /contacts?q=&cursor=&limit=
List, in keyset pages: items, next_cursor, total.
POST /contacts
Find or create by email; 201 created, 200 updated.
GET /contacts/{id}
The contact with its company, deals, tasks and timeline.
GET /companies?q=
List.
POST /companies
Find or create by name.
GET /deals?q=&status=&stage=
List; status is open, won, lost or all.
POST /deals
Create: value_eur (a number, or text such as "15.000" or "15k") or value_cents, stage key, contact_id, company or company_id, next_step, next_step_at.
GET /deals/{id}
The deal with its tasks, timeline and stage history.
PATCH /deals/{id}
Update the fields of an open deal; value_eur as on create.
POST /activities
kind note, call, email, meeting or whatsapp; body; linked with deal_id, contact_id, company_id or contact_email.
POST /tasks
title, due_at, deal_id, contact_id.
POST /calls
Push a transcript: transcript, filename, deal_id, contact_id or contact_email, language de or en. Answers 202; the analysis runs in the background.
GET /calls/{id}
Status and result of an analysis.

Every row comes in the same shape whichever endpoint returns it.

Example: a dialer pushes a finished call

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"}'

The analysis lands on the contact's timeline (and the deal's, when the contact is linked to one) and a call_analysis.done webhook fires. The result carries scores (five dimensions, 1 to 5), strongest_moment, biggest_miss (with what_to_say_instead), three moments and a commitment. biggest_miss and each moment may carry method: the name of the coaching method the analysis applied, present only when it named one. With language en the coaching texts (why, coaching, commitment) are English and a method comes with an English method_label; what_to_say_instead stays in the language of the call and in the form of address the salesperson used, since it is a line for the customer.

Webhooks

Owners and managers register webhooks in the cockpit, on the Team page under Webhooks (URL and events). Every delivery is a POST with:

Content-Type: application/json
X-RZ-Event: deal.created
X-RZ-Delivery: <id>
X-RZ-Signature: sha256=<hex HMAC-SHA256 of the raw body with the webhook secret>

The body is {"id", "event", "created_at", "data"}, where data is the row as the API returns it. Events:

Answer 2xx within 10 seconds; anything else is retried with backoff, 5 attempts in all. Verify the signature before you trust a body. Only https URLs are accepted, and no targets in private networks.