Zum Inhalt springen

Quickstart

1. Sandbox-Schlüssel anlegen

In Bodo: Einstellungen › Schnittstellen › API-Schlüssel › „Schlüssel anlegen“.
Schritt im AssistentenWert für den Quickstart
Umgebungtest, bindet an „Musterfirma GmbH (Sandbox)“
ScopeKontakte: Lesen & Schreiben · Firmen: Lesen · Rest: Kein Zugriff
IP-Bindungdeine aktuelle IP, etwa 198.51.100.7/32 (Pflicht für Schreiben)
Ablauf30 Tage (Vorgabe)
In der Sandbox ist die API schon anDie Sandbox deiner Organisation hat apiAccess bereits auf an, nur mit Testdaten. Für den Quickstart brauchst du deshalb keine Freigabe eines Admins. Einzige Voraussetzung: Deine Organisation hat in Bodo erklärt, ob für sie ein Berufsgeheimnis gilt; ohne diese Erklärung bleibt die API auch in der Sandbox aus. Für einen Live-Schlüssel (live) muss ein Org-Admin die API deiner Organisation erst unter Einstellungen › Schnittstellen › API freigeben; bis dahin fehlt dort der Knopf.

Das Geheimnis wird nur einmal angezeigt. Leg es als Umgebungsvariable ab:

Shell
export BODO_API_KEY="bodo_uk_test_…"

2. Wer bin ich?

GET /v1/me nennt Prinzipal, Organisation und den eigenen Schlüssel mit Ablauf, Pin und wirksamen Scopes.
Anfrage
curl https://api.bodo-app.com/v1/me \
  -H "Authorization: Bearer $BODO_API_KEY"
Antwort
HTTP/1.1 200 OK
Bodo-Version: 2026-11-01
Request-Id: req_01JB6…

{
  "authMethod": "apiKey",
  "principalType": "user",
  "principalId": "usr_…",
  "principalName": "Max Mustermann",
  "organization": {
    "id": "org_…",
    "name": "Musterfirma GmbH (Sandbox)"
  },
  "key": {
    "kidShort": "…Kx9a",
    "environment": "test",
    "versionPin": "2026-11-01",
    "expiresAt": "2026-12-03T09:00:00Z"
  },
  "grant": null,
  "scopes": [
    "contacts:read",
    "contacts:write",
    "companies:read"
  ],
  "openFamilies": [],
  "apiVersion": "2026-11-01"
}

3. Kontakt anlegenPreview

Schreiben startet im Preview-Kanal und braucht deshalb Bodo-Preview: true. Mit der ersten Folgeversion steigt Schreiben für contacts, companies und tasks auf stable auf, dann entfällt der Header. Der Idempotency-Key ist bei POST Pflicht; mit demselben Key ist eine Wiederholung gefahrlos.
curl
curl -X POST https://api.bodo-app.com/v1/contacts \
  -H "Authorization: Bearer $BODO_API_KEY" \
  -H "Bodo-Preview: true" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Erika","lastName":"Mustermann","email":"erika@musterfirma.de"}'

Oder mit dem SDK, das Preview-Header und Idempotency-Key selbst setzt:

// Portal D2 · Quickstart — steps 2 and 3 with the SDK: who am I, then one contact.
// Run: BODO_API_KEY=bodo_uk_test_… bun examples/quickstart.ts
import { Bodo, BodoApiError } from "@bodo/api";

const bodo = new Bodo({
  apiKey: process.env.BODO_API_KEY,
  preview: true, // writes are in the preview channel: sends Bodo-Preview: true
});

// Step 2 · Who am I?
const me = await bodo.me();
console.log(me.principalType, me.authMethod);

// Step 3 · Create a contact. The SDK sets the Idempotency-Key itself, retries included.
try {
  const contact = await bodo.contacts.create({
    firstName: "Erika",
    lastName: "Mustermann",
    email: "erika@musterfirma.de",
  });
  console.log(contact.id, contact.displayName);
} catch (err) {
  if (err instanceof BodoApiError) {
    console.error(err.code, err.requestId); // the stable code, never the text
  }
  throw err;
}
  • 201 Created
  • Location: /v1/contacts/con_…
  • ETag

4. In Bodo nachsehen

Der Kontakt steht in der Sandbox. Die Chronik trägt die Stecker-Marke, die Herkunft ist also sichtbar.
Max Mustermann hat den Kontakt Erika Mustermann angelegt, über die API.Über die API ausgeführtSandboxgerade eben
Weiter zur Referenz