{ "openapi": "3.1.0", "info": { "title": "NexAI CRM — read access and data export", "version": "1.0", "description": "Open interface of the NexAI CRM for data portability and interoperability (Regulation (EU) 2023/2854, Art. 30(2)). Read access to the core records, documents with their stored PDF and e-invoice XML, DATEV files, the complete export and the file package. The data formats of the export are described in crm-datenformate.json.\n\n**Authentication.** An administrator of the organisation creates an API key in the CRM (Einstellungen → API-Keys) and grants it permissions. Send it as `Authorization: Bearer nxk_…` (RFC 6750) or as header `x-api-key: nxk_…`. A key reads only its own organisation's data; without the required permission the answer is 403.\n\n**Responses.** JSON answers are wrapped as `{ \"ok\": true, \"data\": … }`. Paged lists add `nextCursor` (null on the last page); pass it as `cursor` for the next page. Timestamps are RFC 3339 in UTC, dates `YYYY-MM-DD`, amounts integers in cents, quantities in thousandths, VAT rates in basis points, identifiers UUIDs. Field names are the CSV column names in camelCase (`first_name` → `firstName`).\n\n**Errors** carry a JSON body with at least `message`.\n\nInstallations operated by the customer use their own address with the same paths." }, "servers": [ { "url": "https://nexaicrm.de/api" } ], "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Contacts" }, { "name": "Companies" }, { "name": "Leads" }, { "name": "Deals" }, { "name": "Tasks" }, { "name": "Appointments" }, { "name": "Calls" }, { "name": "Files" }, { "name": "Documents" }, { "name": "DATEV" }, { "name": "Export" } ], "paths": { "/contacts": { "get": { "operationId": "listContacts", "tags": [ "Contacts" ], "summary": "List contacts", "description": "Required permission: `contacts.read`.", "x-required-permissions": [ "contacts.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from `nextCursor` of the previous page", "schema": { "type": "string" } }, { "name": "mine", "in": "query", "required": false, "description": "Only records owned by the user who created the API key. Any non-empty value counts as true — omit the parameter to switch the filter off", "schema": { "type": "boolean" } }, { "name": "companyId", "in": "query", "required": false, "description": "Filter by company", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "active", "archived" ] } }, { "name": "owner", "in": "query", "required": false, "description": "Owner: a user id, or `none` for records without owner", "schema": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "string", "const": "none" } ] } }, { "name": "city", "in": "query", "required": false, "description": "City, compared without case and surrounding spaces", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "company", "in": "query", "required": false, "description": "`with` = linked to a company, `without` = not linked", "schema": { "type": "string", "enum": [ "with", "without" ] } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order; without it: newest first", "schema": { "type": "string", "enum": [ "created", "name", "activity" ] } }, { "name": "dir", "in": "query", "required": false, "description": "Sort direction", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/contacts/{id}": { "get": { "operationId": "getContact", "tags": [ "Contacts" ], "summary": "Get one contact", "description": "Required permission: `contacts.read`.", "x-required-permissions": [ "contacts.read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Contact" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/companies": { "get": { "operationId": "listCompanies", "tags": [ "Companies" ], "summary": "List companies", "description": "Required permission: `companies.read`.", "x-required-permissions": [ "companies.read" ], "parameters": [ { "name": "mine", "in": "query", "required": false, "description": "Only records owned by the user who created the API key. Any non-empty value counts as true — omit the parameter to switch the filter off", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from `nextCursor` of the previous page", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/companies/{id}": { "get": { "operationId": "getCompany", "tags": [ "Companies" ], "summary": "Get one company", "description": "Required permission: `companies.read`.", "x-required-permissions": [ "companies.read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Company" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/leads": { "get": { "operationId": "listLeads", "tags": [ "Leads" ], "summary": "List leads", "description": "Required permission: `leads.read`.", "x-required-permissions": [ "leads.read" ], "parameters": [ { "name": "mine", "in": "query", "required": false, "description": "Only records owned by the user who created the API key. Any non-empty value counts as true — omit the parameter to switch the filter off", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from `nextCursor` of the previous page", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "new", "contacted", "qualified", "unqualified", "converted", "lost" ] } }, { "name": "owner", "in": "query", "required": false, "description": "Owner: a user id, or `none` for records without owner", "schema": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "string", "const": "none" } ] } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order; without it: newest first", "schema": { "type": "string", "enum": [ "created", "title", "followup" ] } }, { "name": "dir", "in": "query", "required": false, "description": "Sort direction", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/leads/{id}": { "get": { "operationId": "getLead", "tags": [ "Leads" ], "summary": "Get one lead", "description": "Required permission: `leads.read`.", "x-required-permissions": [ "leads.read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Lead" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/deals": { "get": { "operationId": "listDeals", "tags": [ "Deals" ], "summary": "List deals", "description": "Required permission: `deals.read`.", "x-required-permissions": [ "deals.read" ], "parameters": [ { "name": "mine", "in": "query", "required": false, "description": "Only records owned by the user who created the API key. Any non-empty value counts as true — omit the parameter to switch the filter off", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from `nextCursor` of the previous page", "schema": { "type": "string" } }, { "name": "pipelineId", "in": "query", "required": false, "description": "Filter by pipeline", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "stageId", "in": "query", "required": false, "description": "Filter by stage", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "open", "won", "lost" ] } }, { "name": "owner", "in": "query", "required": false, "description": "Owner: a user id, or `none` for records without owner", "schema": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "string", "const": "none" } ] } }, { "name": "close", "in": "query", "required": false, "description": "Close date: `overdue` (open, expected before today), `month`/`quarter`/`year` (the current one), `none` (open without expected date)", "schema": { "type": "string", "enum": [ "overdue", "month", "quarter", "year", "none" ] } }, { "name": "companyId", "in": "query", "required": false, "description": "Filter by company", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "contactId", "in": "query", "required": false, "description": "Filter by contact", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "lostReason", "in": "query", "required": false, "description": "Reason a deal was lost", "schema": { "type": "string", "enum": [ "price", "competitor", "no_need", "no_budget", "no_response", "timing", "other" ] } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/deals/{id}": { "get": { "operationId": "getDeal", "tags": [ "Deals" ], "summary": "Get one deal", "description": "Required permission: `deals.read`.", "x-required-permissions": [ "deals.read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Deal" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tasks": { "get": { "operationId": "listTasks", "tags": [ "Tasks" ], "summary": "List tasks", "description": "Required permission: `tasks.read`.", "x-required-permissions": [ "tasks.read" ], "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "`open`, `done` or `all`", "schema": { "default": "open", "type": "string", "enum": [ "open", "done", "all" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "default": 200, "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "contactId", "in": "query", "required": false, "description": "Filter by contact", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "companyId", "in": "query", "required": false, "description": "Filter by company", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "assetId", "in": "query", "required": false, "description": "Filter by asset", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "leadId", "in": "query", "required": false, "description": "Filter by lead", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "mine", "in": "query", "required": false, "description": "Only records owned by the user who created the API key. Any non-empty value counts as true — omit the parameter to switch the filter off", "schema": { "type": "boolean" } }, { "name": "owner", "in": "query", "required": false, "description": "Owner: a user id, or `none` for records without owner", "schema": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" }, { "type": "string", "const": "none" } ] } }, { "name": "q", "in": "query", "required": false, "description": "Free-text search", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/tasks/{id}": { "get": { "operationId": "getTask", "tags": [ "Tasks" ], "summary": "Get one task", "description": "Required permission: `tasks.read`.", "x-required-permissions": [ "tasks.read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Task" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/appointments": { "get": { "operationId": "listAppointments", "tags": [ "Appointments" ], "summary": "List appointments", "description": "Not paged: returns up to `limit` appointments.\n\nRequired permission: `appointments.read`.", "x-required-permissions": [ "appointments.read" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "First calendar day (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last calendar day (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "planned", "held", "cancelled" ] } }, { "name": "contactId", "in": "query", "required": false, "description": "Filter by contact", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "companyId", "in": "query", "required": false, "description": "Filter by company", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "dealId", "in": "query", "required": false, "description": "Filter by deal", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "assetId", "in": "query", "required": false, "description": "Filter by asset", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Appointment" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/appointments/{id}": { "get": { "operationId": "getAppointment", "tags": [ "Appointments" ], "summary": "Get one appointment", "description": "Required permission: `appointments.read`.", "x-required-permissions": [ "appointments.read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Appointment" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/calls": { "get": { "operationId": "listCalls", "tags": [ "Calls" ], "summary": "List calls", "description": "Required permission: `calls.read`.", "x-required-permissions": [ "calls.read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "from", "in": "query", "required": false, "description": "First calendar day (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Last calendar day (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from `nextCursor` of the previous page", "schema": { "type": "string" } }, { "name": "contactId", "in": "query", "required": false, "description": "Filter by contact", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "agentId", "in": "query", "required": false, "description": "Filter by sales agent", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "`inbound` or `outbound`", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data", "nextCursor" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Call" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/calls/{id}": { "get": { "operationId": "getCall", "tags": [ "Calls" ], "summary": "Get one call", "description": "Required permission: `calls.read`.", "x-required-permissions": [ "calls.read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Call" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/attachments": { "get": { "operationId": "listAttachments", "tags": [ "Files" ], "summary": "List the files of one record", "description": "No fixed permission: the caller needs the read permission of the record type (contacts.read, companies.read, leads.read, deals.read or assets.read).", "x-required-permissions": [], "parameters": [ { "name": "objectType", "in": "query", "required": true, "description": "Type of the record the files belong to", "schema": { "type": "string", "enum": [ "contact", "company", "lead", "deal", "asset" ] } }, { "name": "recordId", "in": "query", "required": true, "description": "Identifier of that record", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/attachments/{id}/download": { "get": { "operationId": "downloadAttachment", "tags": [ "Files" ], "summary": "Download a file", "description": "The file as uploaded, always as `application/octet-stream`; the original name is in `content-disposition` (RFC 6266, `filename*` in UTF-8). Same permission rule as the list.", "x-required-permissions": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "headers": { "content-disposition": { "description": "attachment; file name of the download", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/documents": { "get": { "operationId": "listDocuments", "tags": [ "Documents" ], "summary": "List documents", "description": "Not paged: the newest `limit` documents matching the filters.\n\nRequired permission: `documents.read`.", "x-required-permissions": [ "documents.read" ], "parameters": [ { "name": "dealId", "in": "query", "required": false, "description": "Filter by deal", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "contactId", "in": "query", "required": false, "description": "Filter by contact", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "companyId", "in": "query", "required": false, "description": "Filter by company", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$" } }, { "name": "kind", "in": "query", "required": false, "description": "Document kind", "schema": { "type": "string", "enum": [ "quote", "order_confirmation", "invoice", "credit_note" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "draft", "sent", "accepted", "declined" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/documents/{id}": { "get": { "operationId": "getDocument", "tags": [ "Documents" ], "summary": "Get one document with its line items", "description": "Required permission: `documents.read`.", "x-required-permissions": [ "documents.read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/Document" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/documents/{id}/pdf": { "get": { "operationId": "getDocumentPdf", "tags": [ "Documents" ], "summary": "The document as PDF/A-3b", "description": "Issued documents are returned exactly as stored, with `x-nexai-sha256`; drafts are rendered on request.\n\nRequired permission: `documents.read`.", "x-required-permissions": [ "documents.read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf" } } }, "headers": { "content-disposition": { "description": "attachment; file name of the download", "schema": { "type": "string" } }, "x-nexai-sha256": { "description": "SHA-256 of the stored file (lower-case hex)", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/documents/{id}/einvoice": { "get": { "operationId": "getDocumentEinvoice", "tags": [ "Documents" ], "summary": "The e-invoice XML (EN 16931, CII)", "description": "The stored XML of an issued e-invoice (ZUGFeRD/Factur-X or XRechnung 3.0), byte for byte. 404 for drafts, quotes and invoices without e-invoice.\n\nRequired permission: `documents.read`.", "x-required-permissions": [ "documents.read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/xml; charset=utf-8": { "schema": { "type": "string", "contentMediaType": "application/xml" } } }, "headers": { "content-disposition": { "description": "attachment; file name of the download", "schema": { "type": "string" } }, "x-nexai-sha256": { "description": "SHA-256 of the stored file (lower-case hex)", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/datev/status": { "get": { "operationId": "getDatevStatus", "tags": [ "DATEV" ], "summary": "What is missing for the DATEV files of a period", "description": "Required permissions (all): `exports.create`, `documents.read`.", "x-required-permissions": [ "exports.create", "documents.read" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "First calendar day (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": true, "description": "Last calendar day (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "$ref": "#/components/schemas/DatevStatus" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/datev/buchungsstapel": { "get": { "operationId": "getDatevBookings", "tags": [ "DATEV" ], "summary": "DATEV booking batch (EXTF 700, category 21)", "description": "Issued invoices and credit notes of the period. Windows-1252, semicolon-separated.\n\nRequired permissions (all): `exports.create`, `documents.read`.", "x-required-permissions": [ "exports.create", "documents.read" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "First calendar day (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": true, "description": "Last calendar day (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "OK", "content": { "text/csv; charset=windows-1252": { "schema": { "type": "string", "contentMediaType": "text/csv" } } }, "headers": { "content-disposition": { "description": "attachment; file name of the download", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/datev/debitoren": { "get": { "operationId": "getDatevDebtors", "tags": [ "DATEV" ], "summary": "DATEV debtor master data (EXTF 700, category 16)", "description": "Required permissions (all): `exports.create`, `documents.read`.", "x-required-permissions": [ "exports.create", "documents.read" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "text/csv; charset=windows-1252": { "schema": { "type": "string", "contentMediaType": "text/csv" } } }, "headers": { "content-disposition": { "description": "attachment; file name of the download", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/datev/umsaetze": { "get": { "operationId": "getRevenueList", "tags": [ "DATEV" ], "summary": "Readable revenue list (CSV, semicolon, Windows-1252)", "description": "Required permissions (all): `exports.create`, `documents.read`.", "x-required-permissions": [ "exports.create", "documents.read" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "First calendar day (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": true, "description": "Last calendar day (YYYY-MM-DD)", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "OK", "content": { "text/csv; charset=windows-1252": { "schema": { "type": "string", "contentMediaType": "text/csv" } } }, "headers": { "content-disposition": { "description": "attachment; file name of the download", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/tenant-export": { "get": { "operationId": "getTenantExport", "tags": [ "Export" ], "summary": "Complete export of the organisation's data", "description": "A ZIP with one CSV file per table (RFC 4180, UTF-8 with BOM) and LIESMICH.txt. Every file and column is described in crm-datenformate.json. Each export is recorded in the audit log.\n\nRequired permissions (all): `exports.create`, `privacy.manage`.", "x-required-permissions": [ "exports.create", "privacy.manage" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/zip": { "schema": { "type": "string", "contentMediaType": "application/zip" } } }, "headers": { "content-disposition": { "description": "attachment; file name of the download", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/tenant-export/dateien": { "get": { "operationId": "getTenantFiles", "tags": [ "Export" ], "summary": "File package: all stored files of the organisation", "description": "A ZIP with every file stored in the CRM, byte for byte: uploaded files (folder dateien/anhaenge/), stored document PDFs (belege/pdf/), e-invoice XML (belege/e-rechnung/), attachments of sent e-mails (mails/anhaenge/) and the organisation's logo (einstellungen/logo.png, .jpg, .svg or .webp by image type; it is not in einstellungen.csv). Every other file name starts with the identifier and a hyphen, followed by the original name (characters a file system cannot hold replaced by _). Plus LIESMICH.txt and zuordnung.csv (same CSV rules, columns below). A part holds at most the chosen size (default 2,000 MB) and 60,000 files, ordered by kind and creation date; further parts via ?teil=2, ?teil=3 … The number of parts is in the header x-nexai-teile and in GET /api/tenant-export/dateien/umfang. Not included: files whose content a retention run already removed, and PDFs of drafts and of quotes or order confirmations never sent by e-mail (rendered on every request). The columns of zuordnung.csv are described in crm-datenformate.json (filePackage).\n\nRequired permissions (all): `exports.create`, `privacy.manage`.", "x-required-permissions": [ "exports.create", "privacy.manage" ], "parameters": [ { "name": "teil", "in": "query", "required": false, "description": "Number of the part to download", "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 100000 } }, { "name": "groesse", "in": "query", "required": false, "description": "Maximum size of a part in MB (1 MB = 1,048,576 bytes)", "schema": { "default": 2000, "type": "integer", "minimum": 1, "maximum": 3500 } } ], "responses": { "200": { "description": "OK", "content": { "application/zip": { "schema": { "type": "string", "contentMediaType": "application/zip" } } }, "headers": { "content-disposition": { "description": "attachment; file name of the download", "schema": { "type": "string" } }, "x-nexai-teil": { "description": "Number of this part", "schema": { "type": "integer" } }, "x-nexai-teile": { "description": "Number of parts in total", "schema": { "type": "integer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/tenant-export/dateien/umfang": { "get": { "operationId": "getTenantFilesSize", "tags": [ "Export" ], "summary": "Size of the file package and number of parts", "description": "Required permissions (all): `exports.create`, `privacy.manage`.", "x-required-permissions": [ "exports.create", "privacy.manage" ], "parameters": [ { "name": "groesse", "in": "query", "required": false, "description": "Maximum size of a part in MB (1 MB = 1,048,576 bytes)", "schema": { "default": 2000, "type": "integer", "minimum": 1, "maximum": 3500 } } ], "responses": { "200": { "description": "OK", "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "const": true }, "data": { "type": "object", "required": [ "dateien", "bytes", "teile", "groesseMb" ], "properties": { "dateien": { "type": "integer", "description": "Number of files" }, "bytes": { "type": "integer", "description": "Total size in bytes" }, "teile": { "type": "integer", "description": "Number of parts at this part size" }, "groesseMb": { "type": "integer", "description": "Part size in MB used for the count" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } } }, "components": { "securitySchemes": { "apiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "nxk_…", "description": "API key as bearer token (RFC 6750)" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "responses": { "BadRequest": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key lacks the required permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Contact": { "type": "object", "description": "A contact (person).", "required": [ "id", "firstName", "lastName", "email", "phone", "companyId", "position", "street", "postalCode", "city", "country", "countryCode", "source", "status", "ownerId", "lastContactedAt", "nextFollowUpAt", "notes", "createdAt", "updatedAt", "deletedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Record identifier" }, "firstName": { "type": [ "string", "null" ], "description": "First name" }, "lastName": { "type": [ "string", "null" ], "description": "Last name" }, "email": { "type": [ "string", "null" ], "description": "E-mail address" }, "phone": { "type": [ "string", "null" ], "description": "Phone number as entered" }, "companyId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related company" }, "position": { "type": [ "string", "null" ], "description": "Job title" }, "street": { "type": [ "string", "null" ], "description": "Street and number" }, "postalCode": { "type": [ "string", "null" ], "description": "Postal code" }, "city": { "type": [ "string", "null" ], "description": "City" }, "country": { "type": [ "string", "null" ], "description": "Country (name)" }, "countryCode": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Country code" }, "source": { "type": [ "string", "null" ], "description": "Origin of the contact" }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Status" }, "ownerId": { "type": [ "string", "null" ], "format": "uuid", "description": "Owner (user)" }, "lastContactedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last contacted at" }, "nextFollowUpAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Next follow-up" }, "notes": { "type": [ "string", "null" ], "description": "Notes (free text)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created at" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last changed at" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Moved to the trash at; empty = not deleted" }, "companyName": { "type": [ "string", "null" ], "description": "List only: name of the linked company (needs companies.read)" }, "lastActivityAt": { "type": "string", "format": "date-time", "description": "List only: latest activity" } }, "additionalProperties": true }, "Company": { "type": "object", "description": "A company.", "required": [ "id", "name", "domain", "phone", "email", "billingEmail", "street", "postalCode", "city", "country", "countryCode", "vatId", "buyerReference", "einvoiceFormat", "notes", "industry", "employeeCount", "primaryContactId", "externalRef", "externalUpdatedAt", "createdAt", "updatedAt", "deletedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Record identifier" }, "name": { "type": "string", "description": "Company name" }, "domain": { "type": [ "string", "null" ], "description": "Web domain" }, "phone": { "type": [ "string", "null" ], "description": "Phone number" }, "email": { "type": [ "string", "null" ], "description": "General e-mail address" }, "billingEmail": { "type": [ "string", "null" ], "description": "E-mail address for invoices" }, "street": { "type": [ "string", "null" ], "description": "Street and number" }, "postalCode": { "type": [ "string", "null" ], "description": "Postal code" }, "city": { "type": [ "string", "null" ], "description": "City" }, "country": { "type": [ "string", "null" ], "description": "Country (name)" }, "countryCode": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Country code" }, "vatId": { "type": [ "string", "null" ], "description": "VAT identification number, without spaces" }, "buyerReference": { "type": [ "string", "null" ], "description": "Buyer reference for e-invoices (BT-10), e.g. the German Leitweg-ID" }, "einvoiceFormat": { "type": "string", "enum": [ "auto", "xrechnung" ], "description": "Preferred e-invoice: auto = ZUGFeRD/Factur-X, xrechnung = XRechnung" }, "notes": { "type": [ "string", "null" ], "description": "Notes (free text)" }, "industry": { "type": [ "string", "null" ], "description": "Industry" }, "employeeCount": { "type": [ "integer", "null" ], "description": "Number of employees" }, "primaryContactId": { "type": [ "string", "null" ], "format": "uuid", "description": "Primary contact" }, "externalRef": { "type": [ "string", "null" ], "description": "Identifier in the upstream system the company is mirrored from" }, "externalUpdatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last state taken over from the upstream system" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created at" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last changed at" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Moved to the trash at; empty = not deleted" } }, "additionalProperties": true }, "Lead": { "type": "object", "description": "A lead.", "required": [ "id", "title", "contactId", "companyId", "status", "source", "ownerId", "notes", "nextFollowUpAt", "createdAt", "updatedAt", "deletedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Record identifier" }, "title": { "type": "string", "description": "Title" }, "contactId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related contact" }, "companyId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related company" }, "status": { "type": "string", "enum": [ "new", "contacted", "qualified", "unqualified", "converted", "lost" ], "description": "Status" }, "source": { "type": [ "string", "null" ], "description": "Origin of the lead" }, "ownerId": { "type": [ "string", "null" ], "format": "uuid", "description": "Owner (user)" }, "notes": { "type": [ "string", "null" ], "description": "Notes (free text)" }, "nextFollowUpAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Next follow-up" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created at" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last changed at" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Moved to the trash at; empty = not deleted" }, "contactName": { "type": [ "string", "null" ], "description": "List only: name of the contact (needs contacts.read)" }, "companyName": { "type": [ "string", "null" ], "description": "List only: name of the company (needs companies.read)" } }, "additionalProperties": true }, "Deal": { "type": "object", "description": "A deal.", "required": [ "id", "title", "pipelineId", "stageId", "contactId", "companyId", "valueCents", "currency", "status", "ownerId", "notes", "expectedCloseAt", "closedAt", "lostReason", "lostNote", "createdAt", "updatedAt", "deletedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Record identifier" }, "title": { "type": "string", "description": "Title" }, "pipelineId": { "type": "string", "format": "uuid", "description": "Pipeline" }, "stageId": { "type": "string", "format": "uuid", "description": "Current stage" }, "contactId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related contact" }, "companyId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related company" }, "valueCents": { "type": "integer", "description": "Value in cents of the currency" }, "currency": { "type": "string", "description": "Currency" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "Open, won or lost" }, "ownerId": { "type": [ "string", "null" ], "format": "uuid", "description": "Owner (user)" }, "notes": { "type": [ "string", "null" ], "description": "Notes (free text)" }, "expectedCloseAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Expected close" }, "closedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Closed at" }, "lostReason": { "type": [ "string", "null" ], "enum": [ "price", "competitor", "no_need", "no_budget", "no_response", "timing", "other", null ], "description": "Reason the deal was lost" }, "lostNote": { "type": [ "string", "null" ], "description": "Note on the loss" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created at" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last changed at" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Moved to the trash at; empty = not deleted" } }, "additionalProperties": true }, "Task": { "type": "object", "description": "A task.", "required": [ "id", "title", "notes", "dueAt", "status", "completedAt", "leadId", "contactId", "ownerId", "createdAt", "deletedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Record identifier" }, "title": { "type": "string", "description": "Title" }, "notes": { "type": [ "string", "null" ], "description": "Notes (free text)" }, "dueAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Due at" }, "status": { "type": "string", "enum": [ "open", "done" ], "description": "Open or done" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Completed at" }, "leadId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related lead" }, "contactId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related contact" }, "ownerId": { "type": [ "string", "null" ], "format": "uuid", "description": "Owner (user)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created at" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Moved to the trash at; empty = not deleted" } }, "additionalProperties": true }, "Appointment": { "type": "object", "description": "An appointment.", "required": [ "id", "title", "startsAt", "endsAt", "place", "notes", "status", "contactId", "companyId", "dealId", "assetId", "ownerId", "locationId", "createdBy", "createdAt", "updatedAt", "deletedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Record identifier" }, "title": { "type": "string", "description": "Title" }, "startsAt": { "type": "string", "format": "date-time", "description": "Start" }, "endsAt": { "type": "string", "format": "date-time", "description": "End" }, "place": { "type": [ "string", "null" ], "description": "Place" }, "notes": { "type": [ "string", "null" ], "description": "Notes (free text)" }, "status": { "type": "string", "enum": [ "planned", "held", "cancelled" ], "description": "Planned, held or cancelled" }, "contactId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related contact" }, "companyId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related company" }, "dealId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related deal" }, "assetId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related asset" }, "ownerId": { "type": [ "string", "null" ], "format": "uuid", "description": "Owner (user)" }, "locationId": { "type": [ "string", "null" ], "format": "uuid", "description": "Location" }, "createdBy": { "type": [ "string", "null" ], "format": "uuid", "description": "Created by (user)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created at" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last changed at" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Moved to the trash at; empty = not deleted" } }, "additionalProperties": true }, "Call": { "type": "object", "description": "A phone call.", "required": [ "id", "externalId", "contactId", "agentId", "reached", "direction", "fromNumber", "toNumber", "startedAt", "endedAt", "durationSeconds", "status", "summary", "intent", "outcome", "department", "followUpRequired", "appointmentAt", "appointmentStatus", "createdAt", "deletedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Record identifier" }, "externalId": { "type": [ "string", "null" ], "description": "Identifier in the source system" }, "contactId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related contact" }, "agentId": { "type": [ "string", "null" ], "format": "uuid", "description": "Sales agent" }, "reached": { "type": [ "boolean", "null" ], "description": "Reached; empty = unknown" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Inbound or outbound" }, "fromNumber": { "type": [ "string", "null" ], "description": "Caller number" }, "toNumber": { "type": [ "string", "null" ], "description": "Called number" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Start" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "End" }, "durationSeconds": { "type": [ "integer", "null" ], "description": "Duration in seconds" }, "status": { "type": "string", "description": "Status as reported by telephony" }, "summary": { "type": [ "string", "null" ], "description": "Summary" }, "intent": { "type": [ "string", "null" ], "description": "Intent" }, "outcome": { "type": [ "string", "null" ], "description": "Outcome" }, "department": { "type": [ "string", "null" ], "description": "Department" }, "followUpRequired": { "type": "boolean", "description": "Follow-up required" }, "appointmentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Agreed appointment" }, "appointmentStatus": { "type": [ "string", "null" ], "enum": [ "confirmed", "tentative", "cancelled", "held", "no_show", null ], "description": "State of the agreed appointment" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created at" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Moved to the trash at; empty = not deleted" } }, "additionalProperties": true }, "Attachment": { "type": "object", "description": "Metadata of an uploaded file.", "required": [ "id", "objectType", "recordId", "filename", "contentType", "sizeBytes", "uploadedBy", "createdAt", "deletedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Record identifier" }, "objectType": { "type": "string", "enum": [ "contact", "company", "lead", "deal", "asset" ], "description": "Type of the record this belongs to" }, "recordId": { "type": "string", "format": "uuid", "description": "Identifier of the record this belongs to (file depends on object_type)" }, "filename": { "type": "string", "description": "Original file name" }, "contentType": { "type": "string", "description": "MIME type at upload" }, "sizeBytes": { "type": "integer", "description": "Size in bytes" }, "uploadedBy": { "type": [ "string", "null" ], "format": "uuid", "description": "Uploaded by" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created at" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Moved to the trash at; empty = not deleted" }, "uploaderName": { "type": [ "string", "null" ], "description": "Display name of the uploader" } }, "additionalProperties": true }, "DocumentRow": { "type": "object", "description": "The stored document record.", "required": [ "id", "kind", "number", "dealId", "contactId", "companyId", "status", "title", "intro", "outro", "buyerReference", "orderReference", "senderSnapshot", "recipientSnapshot", "currency", "validUntil", "issuedOn", "sentAt", "decidedAt", "serviceDate", "servicePeriodStart", "servicePeriodEnd", "dueDate", "cancelsDocumentId", "billingRunId", "smallBusiness", "lockedAt", "einvoiceFormat", "netCents", "taxCents", "grossCents", "ownerId", "locationId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Record identifier" }, "kind": { "type": "string", "enum": [ "quote", "order_confirmation", "invoice", "credit_note" ], "description": "Document kind: quote, order confirmation, invoice, credit note" }, "number": { "type": [ "string", "null" ], "description": "Document number; empty while draft" }, "dealId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related deal" }, "contactId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related contact" }, "companyId": { "type": [ "string", "null" ], "format": "uuid", "description": "Related company" }, "status": { "type": "string", "enum": [ "draft", "sent", "accepted", "declined" ], "description": "draft, sent (issued), accepted or declined (quotes)" }, "title": { "type": "string", "description": "Title" }, "intro": { "type": [ "string", "null" ], "description": "Introductory text" }, "outro": { "type": [ "string", "null" ], "description": "Closing text" }, "buyerReference": { "type": [ "string", "null" ], "description": "Buyer reference (BT-10)" }, "orderReference": { "type": [ "string", "null" ], "description": "Purchase order reference (BT-13)" }, "senderSnapshot": { "description": "Sender at issue as JSON object (name, address, contact, tax and bank details)" }, "recipientSnapshot": { "description": "Recipient at issue as JSON object (company, person, address, email, VAT ID)" }, "currency": { "type": "string", "description": "Currency" }, "validUntil": { "type": [ "string", "null" ], "format": "date", "description": "Quote valid until" }, "issuedOn": { "type": [ "string", "null" ], "format": "date", "description": "Issue date" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Issued at" }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quote decided at" }, "serviceDate": { "type": [ "string", "null" ], "format": "date", "description": "Date of supply" }, "servicePeriodStart": { "type": [ "string", "null" ], "format": "date", "description": "Service period: start" }, "servicePeriodEnd": { "type": [ "string", "null" ], "format": "date", "description": "Service period: end" }, "dueDate": { "type": [ "string", "null" ], "format": "date", "description": "Due date" }, "cancelsDocumentId": { "type": [ "string", "null" ], "format": "uuid", "description": "Invoice this credit note cancels" }, "billingRunId": { "type": [ "string", "null" ], "format": "uuid", "description": "Billing run the document came from" }, "smallBusiness": { "type": "boolean", "description": "Issued under the German small-business rule (§ 19 UStG)" }, "lockedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Locked at (immutable afterwards)" }, "einvoiceFormat": { "type": [ "string", "null" ], "enum": [ "hybrid", "xrechnung", null ], "description": "E-invoice: hybrid = ZUGFeRD/Factur-X, xrechnung = XRechnung; empty = PDF only" }, "netCents": { "type": "integer", "description": "Net total in cents" }, "taxCents": { "type": "integer", "description": "VAT in cents" }, "grossCents": { "type": "integer", "description": "Gross total in cents" }, "ownerId": { "type": [ "string", "null" ], "format": "uuid", "description": "Owner (user)" }, "locationId": { "type": [ "string", "null" ], "format": "uuid", "description": "Location" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created at" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last changed at" } }, "additionalProperties": true }, "DocumentItem": { "type": "object", "description": "A line item of a document.", "required": [ "id", "documentId", "position", "number", "name", "unit", "unitCode", "quantityMilli", "netPriceCents", "taxRateBp", "periodStart", "periodEnd", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Record identifier" }, "documentId": { "type": "string", "format": "uuid", "description": "Document" }, "position": { "type": "integer", "description": "Order" }, "number": { "type": [ "string", "null" ], "description": "Article number" }, "name": { "type": "string", "description": "Name" }, "unit": { "type": "string", "description": "Unit as printed" }, "unitCode": { "type": [ "string", "null" ], "pattern": "^[A-Z0-9]{2,3}$", "description": "Unit code per UN/ECE Recommendation 20 (e.g. H87 = piece)" }, "quantityMilli": { "type": "integer", "description": "Quantity in thousandths (2500 = 2.5)" }, "netPriceCents": { "type": "integer", "description": "Net unit price in cents of the currency" }, "taxRateBp": { "type": "integer", "description": "VAT rate in basis points (1900 = 19 %)" }, "periodStart": { "type": [ "string", "null" ], "format": "date", "description": "Own service period: start" }, "periodEnd": { "type": [ "string", "null" ], "format": "date", "description": "Own service period: end" }, "createdAt": { "type": "string", "format": "date-time", "description": "Created at" }, "netCents": { "type": "integer", "description": "Net amount of the line in cents" }, "taxCents": { "type": "integer", "description": "VAT of the line in cents" }, "grossCents": { "type": "integer", "description": "Gross amount of the line in cents" } }, "additionalProperties": true }, "Document": { "type": "object", "description": "A document (quote, order confirmation, invoice, credit note) with computed figures.", "required": [ "doc", "items", "total", "expired" ], "properties": { "doc": { "$ref": "#/components/schemas/DocumentRow" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentItem" }, "description": "All line items in the single view; empty in lists" }, "total": { "type": "object", "properties": { "netCents": { "type": "integer" }, "taxCents": { "type": "integer" }, "grossCents": { "type": "integer" }, "byRate": { "type": "array", "description": "Totals per VAT rate (single view; empty in lists)", "items": { "type": "object", "properties": { "taxRateBp": { "type": "integer" }, "netCents": { "type": "integer" }, "taxCents": { "type": "integer" } } } } } }, "expired": { "type": "boolean", "description": "Quote past its valid-until date (computed)" }, "payment": { "type": "object", "description": "Invoices and credit notes only: payment state", "properties": { "paidCents": { "type": "integer" }, "openCents": { "type": "integer" }, "status": { "type": "string", "enum": [ "offen", "teilweise", "bezahlt", "ueberzahlt" ] }, "daysOverdue": { "type": [ "integer", "null" ] } } }, "mail": { "type": "object", "description": "List only: state of the latest e-mail that carried this document", "properties": { "status": { "type": "string" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "creditCheck": { "type": "array", "description": "Invoices only: billed periods the contract no longer supports", "items": { "type": "object", "additionalProperties": true } }, "billingWarning": { "type": "boolean", "description": "Invoices only: creditCheck is not empty" } }, "additionalProperties": true }, "DatevStatus": { "type": "object", "required": [ "bereit", "fehlt", "fehlendeKonten" ], "properties": { "bereit": { "type": "boolean", "description": "Everything needed for the DATEV files is set" }, "fehlt": { "type": "array", "items": { "type": "string" }, "description": "What is missing (German)" }, "fehlendeKonten": { "type": "array", "items": { "type": "integer" }, "description": "VAT rates (basis points) in the period without a revenue account" } } }, "Error": { "type": "object", "description": "Error body. `message` is a human-readable sentence (German or English). Validation errors (400) add `code: \"BAD_REQUEST\"` and `issues` per field.", "required": [ "message" ], "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" }, "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } } } }