Die API von AM CRM

Zugriff auf Kontakte, Deals, Termine, Anrufe und Stammdaten einer Organisation — lesen und schreiben, mit Rechten, die du selbst festlegst. Dazu Ereignisse, die dein System benachrichtigen, statt dass es fragen muss.

Schlüssel anlegen: Einstellungen → API-Keys. Dort hakst du an, was er darf.

curl https://am-crm.com/api/v1/me \
  -H "Authorization: Bearer amk_…"

Antwortet das, stimmt alles: Schlüssel gültig, Organisation erkannt, Rechte sichtbar.

Anmeldung

Authorization: Bearer amk_…

Nur als Kopfzeile. Im Adressfeld (?api_key=) nimmt die v1-API keinen Schlüssel an: Adressen landen in Server-Protokollen, Browser-Verläufen und Fehlerberichten.

Der Schlüssel bestimmt die Organisation. Eine workspace_id im Anfragekörper wird nicht geprüft, sondern ignoriert — sie kann nichts bewirken.

Unbekannt, widerrufen und abgelaufen antworten gleich (401). Wer einen Schlüssel errät, soll nicht erfahren, ob er einmal gültig war.

Rechte

Schreiben schliesst Lesen nicht ein. Wer beides braucht, hakt beides an. So kann ein Schlüssel, der nur Leads einliefert, nicht den ganzen Bestand auslesen.

Kontakte und Deals lassen sich über die API nicht löschen. Ein gelöschter Kontakt ist endgültig weg; eine Schnittstelle, über die ein Skript das in einer Schleife tun kann, gibt es deshalb nicht.

Regeln, die überall gelten

Blättern

Jede Liste antwortet mit data und next_cursor. Den Zeiger unverändert als ?cursor= zurückschicken; ist er null, ist das Ende erreicht. Keine Seitenzahlen: wird während des Durchlaufs etwas angelegt, würde damit still ein Datensatz durchfallen.

Grenzen

RateLimit-Policy: "minute";q=120;w=60, "tag";q=20000;w=86400
RateLimit: "minute";r=97;t=41, "tag";r=19873;t=52190

120 Aufrufe je Minute, 20.000 je Tag. Schreibende zählen dreifach. Bei Überschreitung kommt 429 mit Retry-After.

Doppelt abgeschickt

Idempotency-Key: bestellung-4711

Bei jedem POST erlaubt. Derselbe Schlüssel innerhalb von 24 Stunden gibt die gespeicherte erste Antwort zurück, ohne etwas anzulegen. Derselbe Schlüssel mit anderem Inhalt gibt 409 — das ist fast immer ein Fehler im aufrufenden Programm.

Version

Innerhalb von v1 kommen nur Felder und Endpunkte dazu. Nichts wird entfernt, kein Typ geändert, kein Feld nachträglich zur Pflicht. Käme je eine v2, stünden Deprecation und Sunset mindestens sechs Monate vorher in jeder Antwort.

Konto

Kontakte

curl -X POST https://am-crm.com/api/v1/contacts \
  -H "Authorization: Bearer amk_…" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Max","last_name":"Mustermann","email":"max@example.com","phone":"+49 170 1234567","company":"Acme GmbH"}'

curl -X PATCH https://am-crm.com/api/v1/contacts/{id} \
  -H "Authorization: Bearer amk_…" \
  -H "Content-Type: application/json" \
  -d '{"status":"Termin vereinbart","notes":"Ruft nächste Woche zurück."}'

curl -X POST https://am-crm.com/api/v1/contacts/{id}/persons \
  -H "Authorization: Bearer amk_…" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Erika","last_name":"Musterfrau","job_title":"Einkauf","is_primary":true}'

curl -X POST https://am-crm.com/api/v1/contacts/{id}/activities \
  -H "Authorization: Bearer amk_…" \
  -H "Content-Type: application/json" \
  -d '{"type":"note","body":"Angebot per Post verschickt."}'

Deals

curl -X POST https://am-crm.com/api/v1/deals \
  -H "Authorization: Bearer amk_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"Jahreslizenz","contact_id":"…","value_cents":199900,"currency":"EUR"}'

curl -X PATCH https://am-crm.com/api/v1/deals/{id} \
  -H "Authorization: Bearer amk_…" \
  -H "Content-Type: application/json" \
  -d '{"stage_id":"…"}'

Termine

curl -X POST https://am-crm.com/api/v1/appointments \
  -H "Authorization: Bearer amk_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"Erstgespräch","starts_at":"2026-09-10T10:00:00Z","ends_at":"2026-09-10T10:30:00Z"}'

curl -X PATCH https://am-crm.com/api/v1/appointments/{id} \
  -H "Authorization: Bearer amk_…" \
  -H "Content-Type: application/json" \
  -d '{"starts_at":"2026-09-11T14:00:00Z","ends_at":"2026-09-11T14:30:00Z"}'

Anrufe

Stammdaten

Ereignis-Abos

curl -X POST https://am-crm.com/api/v1/webhooks \
  -H "Authorization: Bearer amk_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/am-crm","events":["contact.created","deal.won"]}'

Ereignisse

Statt zu fragen, ob sich etwas geändert hat, lässt du dich benachrichtigen. Abo anlegen über POST /api/v1/webhooks; die Antwort enthält EINMAL das Geheimnis.

Unterschrift prüfen

Nach Standard Webhooks — dafür gibt es fertige Bibliotheken. Von Hand:

// Kopfzeilen: webhook-id, webhook-timestamp, webhook-signature
const inhalt = `${id}.${zeitstempel}.${rohkoerper}`;
const erwartet = 'v1,' + crypto
  .createHmac('sha256', Buffer.from(geheimnis.slice(6), 'base64'))
  .update(inhalt).digest('base64');
// Zeitstempel älter als 5 Minuten: ablehnen (Schutz vor Wiedereinspielung).

Wichtig: über den ROHEN Körper unterschreiben, nicht über neu verpacktes JSON. Antworte mit 2xx; alles andere gilt als Fehlschlag und wird bis zu dreimal wiederholt. Benutze webhook-id als Idempotenz-Schlüssel — Zustellungen können sich wiederholen.

Fremde Apps — OAuth 2.1

Ein API-Schlüssel gehört der Organisation und wird von ihrem Inhaber in sein eigenes System getragen. Baust du eine App, die sich Nutzer verbinden, nimm OAuth: dann sieht der Nutzer, wer was will, sagt einmal ja und kann genau deiner App den Zugang wieder nehmen.

Einrichten

Deine App kann sich selbst registrieren — kein Antrag, kein Warten:

curl -X POST https://am-crm.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"Meine App",
       "redirect_uris":["https://meine-app.de/oauth/callback"],
       "scope":"contacts.read contacts.write"}'

Antwort: deine client_id. Ein client_secret gibt es nicht — selbst registrierte Apps sind öffentlich und sichern sich über PKCE. Alle Adressen stehen maschinenlesbar unter /.well-known/oauth-authorization-server.

Der Ablauf

1. PKCE erzeugen
   verifier  = 43-128 zufällige Zeichen
   challenge = base64url(sha256(verifier))

2. Nutzer hinschicken
   https://am-crm.com/oauth/authorize
     ?client_id=amc_…
     &redirect_uri=https://meine-app.de/oauth/callback   (exakt wie registriert)
     &response_type=code
     &scope=contacts.read+contacts.write
     &state=<eigener Zufallswert>
     &code_challenge=<challenge>
     &code_challenge_method=S256

3. Rücksprung mit ?code=…&state=…   (state vergleichen!)

4. Code eintauschen
   POST https://am-crm.com/api/oauth/token
     grant_type=authorization_code
     client_id=amc_…  code=…  code_verifier=<verifier>
     redirect_uri=…

   → { "access_token": "amo_…", "expires_in": 3600,
       "refresh_token": "amr_…", "scope": "…" }

5. Aufrufen wie mit einem Schlüssel
   Authorization: Bearer amo_…

Was du beachten musst

• PKCE ist Pflicht, nur S256. plain wird abgelehnt.
• Ein Code, ein Mal. Ein zweites Einlösen widerruft, was aus ihm entstand — das ist der Schutz gegen abgefangene Codes.
• Jedes Erneuern dreht das Token weiter. Das alte Paar stirbt sofort. Benutzt du ein altes refresh_token ein zweites Mal, wird der ganze Zugang widerrufen und der Nutzer muss erneut zustimmen — speichere also immer das zuletzt erhaltene.
• Rücksprung-Adressen müssen exakt stimmen. Zeichen für Zeichen, kein Präfix. https ist Pflicht; http://localhost und eigene App-Schemata sind erlaubt.
• Zugang beenden: POST /api/oauth/revoke mit token=… (RFC 7009).

KI-Agenten — MCP

Unter https://am-crm.com/api/mcp steht ein MCP-Server. Er ist eine Ansicht auf genau diese API: jeder Werkzeugaufruf geht durch dieselbe Route, dieselben Rechte, dieselbe Ratenzählung. Ein Agent kann damit nichts, was der Zugang nicht ohnehin dürfte.

{
  "mcpServers": {
    "am-crm": {
      "url": "https://am-crm.com/api/mcp",
      "headers": { "Authorization": "Bearer amk_…" }
    }
  }
}

Clients, die OAuth können, brauchen den Schlüssel nicht: sie bekommen auf einen Aufruf ohne Anmeldung eine 401 mit WWW-Authenticate, finden darüber den Autorisierungsserver und führen den Nutzer durch die Zustimmung.

tools/list zeigt nur, was dieser Zugang wirklich darf — ein Werkzeug anzubieten, das dann mit 403 antwortet, kostet einen Aufruf und eine Erklärung.

Fehler

Immer application/problem+json nach RFC 9457.

{
  "type": "https://am-crm.com/docs/api/errors/validation-failed",
  "title": "Die Eingabe ist unvollständig oder falsch.",
  "status": 422,
  "code": "validation_failed",
  "detail": "first_name: darf nicht leer sein",
  "instance": "/api/v1/contacts",
  "request_id": "req_9f2c…",
  "errors": [
    {
      "field": "first_name",
      "message": "darf nicht leer sein"
    }
  ]
}

Jede Antwort trägt X-Request-Id. Nenne diese Kennung bei einer Störung — damit finden wir den Aufruf im Protokoll wieder, das auch du in den Einstellungen siehst.