{"openapi":"3.1.0","info":{"title":"Safebird API","version":"1.0.0","summary":"Read Safebird broker workspace data: leads, DIN needs analyses, households, appointments, meeting intelligence, sales signals, the event feed, and REST-Hooks subscriptions.","description":"Safebird is an AI assistant for insurance brokers in Germany. Every broker workspace exposes its own data through this versioned, read-mostly REST API (plus REST-Hooks for Zapier/Make and an MCP server for AI agents).\n\n**Authentication:** workspace-wide API keys created in the Safebird dashboard (Integrations → API & Webhooks). Send the key as `Authorization: Bearer sb_live_…`. Keys carry scopes; each operation lists the scope it requires.\n\n**Rate limit:** 240 requests per minute per key. Failed authentications are additionally throttled per IP.\n\n**Envelope:** Every response carries `api_version` plus either `data` (success) or `error` (failure). List responses add `meta` (count / limit / offset, or `next_cursor` for the event feed).\n\n**Caching:** all responses are `Cache-Control: no-store` because they contain personal data.\n\n**MCP server (for AI agents):** https://safebird.ai/api/mcp — Streamable HTTP, same Bearer authentication. Human docs: https://safebird.ai/developers.","termsOfService":"https://safebird.ai/agb","contact":{"name":"Safebird","url":"https://safebird.ai/developers","email":"info@safebird.ai"}},"externalDocs":{"description":"Developer documentation","url":"https://safebird.ai/developers"},"servers":[{"url":"https://safebird.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Leads","description":"Leads in the broker pipeline and their DIN needs analysis."},{"name":"Kontakte","description":"Household records per contact (accumulated DIN needs profile)."},{"name":"Appointments","description":"Broker appointments and meeting intelligence."},{"name":"Signals","description":"Sales signals (Vertriebsimpulse)."},{"name":"Events","description":"Cursor-paginated event feed (pull alternative to webhooks)."},{"name":"Hooks","description":"REST-Hooks webhook subscriptions (Zapier/Make pattern)."},{"name":"Schemas","description":"Machine-readable JSON schemas of the analysis payloads."}],"paths":{"/leads":{"get":{"operationId":"listLeads","tags":["Leads"],"summary":"List leads","description":"Leads of the workspace pipeline, newest first. Requires scope `read:leads`.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–200, default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"description":"Zero-based offset into the result set.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","required":false,"description":"Filter by pipeline status.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Case-insensitive substring match on name, email, or phone.","schema":{"type":"string"}},{"name":"include_archived","in":"query","required":false,"description":"Include archived leads when `true`.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Lead list.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/leads/{leadId}":{"get":{"operationId":"getLead","tags":["Leads"],"summary":"Get a lead","description":"One lead including parsed contact data. Requires scope `read:leads`.","parameters":[{"name":"leadId","in":"path","required":true,"description":"Lead id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The lead.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"$ref":"#/components/schemas/Lead"}}}}}},"400":{"description":"`leadId` is not a UUID (`invalid_id`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Lead not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/leads/{leadId}/analysis":{"get":{"operationId":"getLeadAnalysis","tags":["Leads"],"summary":"Get the DIN needs analysis of a lead","description":"The canonical DIN 77230 needs analysis of a lead: flat export projection (`analysis`), nested din_core_v2 form (`analysis_v2`) and the DIN check. Raw income amounts are stripped. Requires scope `read:analyses`.","parameters":[{"name":"leadId","in":"path","required":true,"description":"Lead id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The analysis.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"$ref":"#/components/schemas/LeadAnalysis"}}}}}},"400":{"description":"`leadId` is not a UUID (`invalid_id`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No parsed analysis for this lead (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/kontakte":{"get":{"operationId":"listKontakte","tags":["Kontakte"],"summary":"List household records","description":"One entry per contact: contract count, DIN gaps per need level, parameter version. Requires scope `read:kontakte`.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–200, default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"description":"Zero-based offset into the result set.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Household list.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"type":"array","items":{"$ref":"#/components/schemas/KontaktSummary"}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/kontakte/{key}":{"get":{"operationId":"getKontakt","tags":["Kontakte"],"summary":"Get a household record by any identity form","description":"Like `/kontakte/{key}/haushalt` but alias-resolving: `key` may be any identity form (`email:…`, `phone:…`, `lead:…`, a bare email or phone number, raw or normalised). The response carries `canonical_key` and `aliases` so integrations survive key changes after merges. Requires scope `read:kontakte`.","parameters":[{"name":"key","in":"path","required":true,"description":"Identity key or alias, URL-encoded.","schema":{"type":"string"}}],"responses":{"200":{"description":"The household record.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"$ref":"#/components/schemas/Haushalt"}}}}}},"400":{"description":"Key missing or malformed (`invalid_request`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No household record for this contact (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/kontakte/{key}/haushalt":{"get":{"operationId":"getHaushalt","tags":["Kontakte"],"summary":"Get the accumulated DIN needs profile of a contact","description":"The household record for the exact identity key (`email:…` / `phone:…` / `lead:…`, URL-encoded), din_core_v2 form incl. DIN check, without raw income amounts. Requires scope `read:kontakte`.","parameters":[{"name":"key","in":"path","required":true,"description":"Exact identity key, URL-encoded.","schema":{"type":"string"}}],"responses":{"200":{"description":"The household record.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"$ref":"#/components/schemas/Haushalt"}}}}}},"400":{"description":"Key missing (`invalid_request`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No household record for this contact (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/appointments":{"get":{"operationId":"listAppointments","tags":["Appointments"],"summary":"List appointments","description":"Appointments of the workspace, newest first. Requires scope `read:appointments`.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–200, default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"description":"Zero-based offset into the result set.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","required":false,"description":"Filter by appointment status.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Only appointments starting at or after this ISO 8601 timestamp.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Appointment list.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Appointment"}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/meetings/{meetingId}/intelligence":{"get":{"operationId":"getMeetingIntelligence","tags":["Appointments"],"summary":"Get meeting intelligence for an appointment","description":"Summary, next steps, and scored fields with rationale for one appointment. Requires scope `read:meetings`.","parameters":[{"name":"meetingId","in":"path","required":true,"description":"Appointment id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Meeting intelligence.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"$ref":"#/components/schemas/MeetingIntelligence"}}}}}},"400":{"description":"`meetingId` is not a UUID (`invalid_id`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Meeting not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/signals":{"get":{"operationId":"listSignals","tags":["Signals"],"summary":"List sales signals","description":"Sales signals (Vertriebsimpulse): kind, title, status, score — titles only, no detail texts. Requires scope `read:signals` (opt-in, not part of default key scopes).","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–200, default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"description":"Zero-based offset into the result set.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","required":false,"description":"Filter by status.","schema":{"type":"string","enum":["open","dismissed","done","resolved"]}}],"responses":{"200":{"description":"Signal list.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}}},"400":{"description":"Unknown `status` (`invalid_request`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/events":{"get":{"operationId":"listEvents","tags":["Events"],"summary":"Read the event feed","description":"Cursor-paginated, at-least-once event feed. Persist `meta.next_cursor` and pass it back as `after` so no event is missed even without webhooks; dedupe replays via event `id`. Requires scope `read:events` (note: payloads contain lead, analysis and household data).","parameters":[{"name":"after","in":"query","required":false,"description":"Cursor of the last processed event (non-negative integer).","schema":{"type":"integer","minimum":0}},{"name":"types","in":"query","required":false,"description":"Comma-separated list of event types to include.","schema":{"type":"string"},"example":"lead.created,analysis.completed"},{"name":"limit","in":"query","required":false,"description":"Page size (max 200).","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Events in ascending cursor order.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"integer"},"count":{"type":"integer"}}}}}}}},"400":{"description":"Bad `after` cursor (`invalid_cursor`) or unknown `types` (`invalid_types`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Cursor below the retention horizon (`cursor_expired`): reset by omitting `after`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/hooks":{"get":{"operationId":"listHooks","tags":["Hooks"],"summary":"List webhook subscriptions","description":"Requires scope `write:hooks`.","responses":{"200":{"description":"Subscriptions.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"type":"array","items":{"$ref":"#/components/schemas/HookSubscription"}},"meta":{"type":"object","properties":{"count":{"type":"integer"}}}}}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createHook","tags":["Hooks"],"summary":"Create a webhook subscription","description":"REST-Hooks pattern (Zapier/Make instant triggers). Deliveries are HTTPS POSTs signed with HMAC-SHA256 (`X-Safebird-Signature: v1=<hex>` over `<timestamp>.<body>`), retried with exponential backoff on 429/5xx. Requires scope `write:hooks`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target_url","event_types"],"properties":{"target_url":{"type":"string","format":"uri","description":"HTTPS endpoint that receives the events."},"event_types":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/EventType"}},"label":{"type":"string"},"source":{"type":"string","enum":["api","zapier","make"],"default":"api"}}}}}},"responses":{"201":{"description":"Subscription created.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"$ref":"#/components/schemas/HookSubscription"}}}}}},"400":{"description":"Body not JSON (`invalid_json`), `target_url` missing (`missing_target_url`), bad `event_types` (`invalid_event_types`), or rejected URL (`invalid_subscription`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/hooks/{hookId}":{"delete":{"operationId":"deleteHook","tags":["Hooks"],"summary":"Delete a webhook subscription","description":"Requires scope `write:hooks`.","parameters":[{"name":"hookId","in":"path","required":true,"description":"Subscription id (UUID).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"type":"object","properties":{"deleted":{"type":"boolean","const":true}}}}}}}},"400":{"description":"`hookId` is not a UUID (`invalid_id`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Subscription not found (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/hooks/sample":{"get":{"operationId":"getHookSamples","tags":["Hooks"],"summary":"Sample event payloads","description":"Example envelopes per event type, e.g. for field mapping in Zapier or Make. Requires scope `write:hooks`.","parameters":[{"name":"type","in":"query","required":false,"description":"Return only this event type.","schema":{"$ref":"#/components/schemas/EventType"}}],"responses":{"200":{"description":"Sample envelopes.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}},"400":{"description":"Unknown `type` (`unknown_event_type`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/schemas/analysis":{"get":{"operationId":"getAnalysisSchemas","tags":["Schemas"],"summary":"JSON schemas of the analysis payloads","description":"Canonical extraction schema (din_core_v2 core + product fragments), DIN check schema, and the flat projection. Requires scope `read:analyses`.","responses":{"200":{"description":"Schema registry.","content":{"application/json":{"schema":{"type":"object","required":["api_version","data"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"data":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"Missing or unknown API key (`missing_token`, `invalid_token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks the required scope (`missing_scope`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`); honour `Retry-After` when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected failure (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Workspace API key (`sb_live_…`) created in the Safebird dashboard under Integrations → API & Webhooks."}},"schemas":{"ApiVersion":{"type":"string","const":"v1"},"ErrorResponse":{"type":"object","required":["api_version","error"],"properties":{"api_version":{"$ref":"#/components/schemas/ApiVersion"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code.","enum":["missing_token","invalid_token","missing_scope","rate_limited","invalid_id","invalid_request","invalid_json","invalid_cursor","invalid_types","invalid_event_types","invalid_subscription","missing_target_url","unknown_event_type","cursor_expired","not_found","internal_error"]},"message":{"type":"string","description":"Human-readable explanation, often with a resolution hint."}}}}},"EventType":{"type":"string","enum":["lead.created","lead.stage_changed","lead.archived","analysis.completed","din.check_completed","haushalt.updated","kontakt.merged","appointment.scheduled","appointment.cancelled","appointment.updated","meeting.intelligence_ready","meeting.intelligence_failed","advisory_doc.approved","advisory_doc.sent","signal.opened","signal.status_changed","signal.outcome_recorded"]},"Lead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"status":{"type":"string"},"source_type":{"type":["string","null"]},"contacted_at":{"type":["string","null"],"format":"date-time"},"archived_at":{"type":["string","null"],"format":"date-time"},"archive_reason_code":{"type":["string","null"]},"parsed_data":{"type":["object","null"],"additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"LeadAnalysis":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["chat","call"]},"source_id":{"type":"string"},"analysis_schema_version":{"type":["string","null"]},"analysis":{"type":"object","additionalProperties":true,"description":"Flat export projection."},"analysis_v2":{"type":["object","null"],"additionalProperties":true,"description":"Nested din_core_v2 form."},"din_check":{"type":["object","null"],"additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"KontaktSummary":{"type":"object","properties":{"kontakt_key":{"type":"string"},"vertraege_anzahl":{"type":"integer"},"luecken_nach_stufe":{"type":"array","items":{"type":"object","properties":{"stufe":{"type":"integer"},"anzahl":{"type":"integer"}}}},"params_version":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}}},"Haushalt":{"type":"object","properties":{"kontakt_key":{"type":"string"},"canonical_key":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"haushalt":{"type":"object","additionalProperties":true,"description":"din_core_v2 household profile without raw income amounts."},"provenance":{"type":["object","null"],"additionalProperties":true},"din_check":{"type":["object","null"],"additionalProperties":true},"empfehlungen_aktuell":{"type":["object","null"],"additionalProperties":true},"updated_at":{"type":"string","format":"date-time"}}},"Appointment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":["string","null"]},"status":{"type":"string"},"platform":{"type":"string"},"meeting_url":{"type":["string","null"],"format":"uri"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"customer_display_name":{"type":["string","null"]},"source":{"type":["string","null"]},"intelligence_status":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"MeetingIntelligence":{"type":"object","properties":{"appointment":{"$ref":"#/components/schemas/Appointment"},"overall_score":{"type":["number","null"]},"customer_persona":{"type":["string","null"]},"conversation_type":{"type":["string","null"]},"results":{"type":"array","items":{"type":"object","properties":{"field_key":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"output_type":{"type":"string"},"status":{"type":"string"},"value":{"description":"Field value; shape depends on `output_type`."},"score":{"type":["number","null"]},"level":{"type":["string","null"]},"rationale":{"type":["string","null"]},"recommendation":{"type":["string","null"]},"generated_at":{"type":["string","null"],"format":"date-time"}}}}}},"Signal":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["open","dismissed","done","resolved"]},"score":{"type":"number"},"lead_id":{"type":["string","null"],"format":"uuid"},"detected_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Event":{"type":"object","description":"Event envelope shared by webhook deliveries and the /events feed.","properties":{"id":{"type":"string","format":"uuid"},"event_type":{"$ref":"#/components/schemas/EventType"},"schema_version":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"object_type":{"type":"string"},"object_id":{"type":"string"},"links":{"type":"object","properties":{"lead_id":{"type":["string","null"],"format":"uuid"},"session_id":{"type":["string","null"],"format":"uuid"}}},"data":{"type":"object","additionalProperties":true,"description":"Type-specific payload, versioned via `schema_version`."},"cursor":{"type":"integer","description":"Feed position (only on /events)."}}},"HookSubscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"target_url":{"type":"string","format":"uri"},"event_types":{"type":"array","items":{"$ref":"#/components/schemas/EventType"}},"label":{"type":["string","null"]},"source":{"type":"string","enum":["api","zapier","make"]},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}}}