{ "openapi": "3.1.0", "info": { "title": "First AI Employee Client API", "version": "1.0.0", "description": "OAuth 2.0 API for tenant-owned operational data. Writes are bounded by explicit scopes, durable idempotency or closed lifecycle transitions. The API is unavailable unless First AI Employee explicitly enables it." }, "servers": [ { "url": "https://api.firstaiemployee.com/api/client/v1" } ], "security": [ { "OAuth2": [] } ], "paths": { "/": { "get": { "summary": "API discovery", "operationId": "getApiDiscovery", "parameters": [], "responses": { "200": { "description": "Version and resource links.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDiscovery" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/me": { "get": { "summary": "Current tenant and grant", "operationId": "getCurrentClient", "parameters": [], "responses": { "200": { "description": "The tenant selected by the bearer grant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentClient" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/openapi.json": { "get": { "summary": "OpenAPI document", "operationId": "getOpenApiDocument", "parameters": [], "responses": { "200": { "description": "This OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/calls": { "get": { "summary": "calls", "operationId": "listcalls", "security": [ { "OAuth2": [ "calls:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Call" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts": { "get": { "summary": "contacts", "operationId": "listcontacts", "security": [ { "OAuth2": [ "contacts:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/contacts": { "get": { "summary": "CRM contacts", "operationId": "listCRMcontacts", "security": [ { "OAuth2": [ "contacts:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "email", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "phone", "in": "query", "schema": { "type": "string", "maxLength": 50 } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Optional comma-separated selection: id, name, phone, email, notes, tags, classification, total_jobs, lifetime_value, consent, first_seen_at, last_seen_at, created_at, updated_at, lead_source, lifecycle_stage, qualification, revision." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmContact" } }, "page": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "request_id", "version", "limit", "has_more", "next_cursor" ] } }, "required": [ "data", "page", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/contacts/{id}": { "get": { "summary": "Read one CRM contact", "operationId": "getCrmContact", "security": [ { "OAuth2": [ "contacts:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Optional comma-separated selection: id, name, phone, email, notes, tags, classification, total_jobs, lifetime_value, consent, first_seen_at, last_seen_at, created_at, updated_at, lead_source, lifecycle_stage, qualification, revision." } ], "responses": { "200": { "description": "The tenant-owned CRM contact and its strong ETag.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CrmContact" }, "meta": { "type": "object", "required": [ "request_id", "version" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Contact not found in this tenant." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/contacts:preview": { "post": { "summary": "Preview a CRM contact create or update without changing data", "operationId": "previewCrmContactUpsert", "security": [ { "OAuth2": [ "contacts:write" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmContactInput" } } } }, "responses": { "200": { "description": "Exact before/after preview and commit binding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactUpsertPreview" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/contacts:commit": { "post": { "summary": "Commit a previously previewed CRM contact create or update", "operationId": "commitCrmContactUpsert", "security": [ { "OAuth2": [ "contacts:write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 256 } }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required for updates; use the ETag returned by GET or preview." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "phone", "expected_revision" ], "properties": { "phone": { "$ref": "#/components/schemas/CrmContactInput/properties/phone" }, "email": { "$ref": "#/components/schemas/CrmContactInput/properties/email" }, "name": { "$ref": "#/components/schemas/CrmContactInput/properties/name" }, "expected_revision": { "type": [ "integer", "null" ], "minimum": 1 }, "preview_key": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Existing contact updated or already current.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmContact" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "outcome": { "type": "string" } }, "required": [ "request_id", "version", "outcome" ] } }, "required": [ "data", "meta" ] } } } }, "201": { "description": "Contact created.", "headers": { "Location": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmContact" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "outcome": { "type": "string" } }, "required": [ "request_id", "version", "outcome" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Idempotency, preview, or revision conflict." }, "428": { "description": "If-Match is required for an update." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms": { "get": { "summary": "forms", "operationId": "listforms", "security": [ { "OAuth2": [ "front_desk:forms:read" ] }, { "OAuth2": [ "forms:lifecycle" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "status", "in": "query", "schema": { "enum": [ "draft", "published", "closed" ] } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Optional comma-separated selection: id, ref, title, status, version, received_responses, created_at, updated_at, published_at, draft_revision." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormsAuthoringForm" } }, "page": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "request_id", "version", "limit", "has_more", "next_cursor" ] } }, "required": [ "data", "page", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "summary": "Create an unpublished form draft", "operationId": "createForm", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "description": "Requires CLIENT_API_ENABLED=on, a registered client, an owner-consented forms:lifecycle grant, and live Forms entitlement. One Idempotency-Key (16 to 128 chars) binds the tenant, client, grant, operation, and canonical request; exact retries replay for 24 hours.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" }, "description": "One value only. Same request replays; different request returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "definition" ], "properties": { "definition": { "type": "object" }, "ref": { "type": "string", "maxLength": 64 } } } } } }, "responses": { "201": { "description": "Unpublished draft created.", "headers": { "Location": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormsAuthoringForm" }, "meta": { "$ref": "#/components/schemas/FormsAuthoringMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Idempotency key mismatch, concurrent in-flight request, or deterministic command conflict." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{id}": { "get": { "summary": "Read one form draft definition", "operationId": "getForm", "security": [ { "OAuth2": [ "front_desk:forms:read" ] }, { "OAuth2": [ "forms:lifecycle" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Optional comma-separated selection: id, ref, title, status, version, received_responses, created_at, updated_at, published_at, draft_revision, definition. Select definition explicitly to retrieve the draft. id is always included." } ], "responses": { "200": { "description": "The tenant-owned form and strong draft ETag.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormsAuthoringForm" }, "meta": { "$ref": "#/components/schemas/FormsAuthoringMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form not found." }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "summary": "Delete only a never-published empty draft", "operationId": "deleteEmptyFormDraft", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "description": "Requires CLIENT_API_ENABLED=on, a registered client, an owner-consented forms:lifecycle grant, and the current strong ETag plus canonical draft revision. Only an empty never-published draft can be deleted; published forms and response history are out of scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"v1:[a-f0-9]{32}\"$" }, "description": "One current strong ETag. The body must also contain the current draft revision." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_draft_revision" ], "properties": { "expected_draft_revision": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Empty never-published draft deleted.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormsAuthoringDeleted" }, "meta": { "$ref": "#/components/schemas/FormsAuthoringMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form not found in this tenant." }, "409": { "description": "Idempotency, revision, or delete-policy conflict." }, "428": { "description": "If-Match is required." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{formId}/scheduling": { "get": { "summary": "Read bounded scheduling configuration", "operationId": "getFormSchedulingConfiguration", "description": "Returns sanitized scheduler-question settings from the current form draft. It does not query provider availability or create a booking.", "security": [ { "OAuth2": [ "front_desk:forms:read" ] } ], "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scheduler fields and explicit no-provider-effect markers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FormScheduling" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" } }, "required": [ "request_id" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form not found in this tenant." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{id}:applyOperations": { "post": { "summary": "Apply a closed batch of edit operations to one form draft", "operationId": "applyFormOperations", "security": [ { "OAuth2": [ "forms:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 256 } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Strong ETag returned by GET /forms/{id}." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "version", "operations", "expected_draft_revision" ], "properties": { "version": { "type": "integer", "const": 1 }, "operations": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object" } }, "expected_draft_revision": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Saved draft, operation summary, and exact diff.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormsAuthoringApplied" }, "meta": { "$ref": "#/components/schemas/FormsAuthoringMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Draft revision, idempotency, or operation conflict." }, "428": { "description": "If-Match is required." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/validate": { "post": { "summary": "Validate a form definition without persisting", "operationId": "validateFormDefinition", "security": [ { "OAuth2": [ "forms:write" ] }, { "OAuth2": [ "forms:lifecycle" ] } ], "description": "Requires CLIENT_API_ENABLED=on, a registered client, and a forms:write or owner-consented forms:lifecycle grant. Canonical semantic validation only; a valid document is not a publication approval.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "definition" ], "properties": { "definition": { "type": "object" } } } } } }, "responses": { "200": { "description": "Semantic validation result; publication_authorized is always false.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormsAuthoringValidation" }, "meta": { "$ref": "#/components/schemas/FormsAuthoringMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{id}/duplicate": { "post": { "summary": "Copy a definition into a new draft", "operationId": "duplicateForm", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "description": "Requires CLIENT_API_ENABLED=on, a registered client, an owner-consented forms:lifecycle grant, and live Forms entitlement. New draft carries stable child refs and no responses.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"v1:[a-f0-9]{32}\"$" }, "description": "One current strong ETag. The body must also contain the current draft revision." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ref", "expected_draft_revision" ], "properties": { "ref": { "type": "string", "maxLength": 64 }, "title": { "type": "string", "maxLength": 300 }, "expected_draft_revision": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "New draft duplicated.", "headers": { "Location": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormsAuthoringForm" }, "meta": { "$ref": "#/components/schemas/FormsAuthoringMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form not found in this tenant." }, "409": { "description": "Idempotency, revision, or duplicate conflict." }, "428": { "description": "If-Match is required." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{id}/publish-preview": { "post": { "summary": "Review the exact publish candidate", "operationId": "prepareFormPublish", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "description": "Requires CLIENT_API_ENABLED=on, a registered client, an owner-consented forms:lifecycle grant, and live Forms entitlement. No publication occurs. Preview receipts expire after ten minutes; reuse the same Idempotency-Key for publication.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"v1:[a-f0-9]{32}\"$" }, "description": "One current strong ETag. The body must also contain the current draft revision." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_draft_revision", "expected_published_version" ], "properties": { "expected_draft_revision": { "type": "string", "format": "date-time" }, "expected_published_version": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Exact publish candidate and expiring preview receipt.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormsAuthoringPreparedPreview" }, "meta": { "$ref": "#/components/schemas/FormsAuthoringMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form not found in this tenant." }, "409": { "description": "Idempotency, revision, or review-gate conflict." }, "428": { "description": "If-Match is required." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{id}/publish": { "post": { "summary": "Publish the approved preview as a new revision", "operationId": "publishForm", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "description": "Requires CLIENT_API_ENABLED=on, a registered client, an owner-consented forms:lifecycle grant, and live Forms entitlement. Requires the preview receipt, unchanged revisions, and confirmed:true. Never publish automatically from validation.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" }, "description": "Reuse the preview key. Same request replays; different request returns 409." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"v1:[a-f0-9]{32}\"$" }, "description": "One current strong ETag. The body must also contain the current draft revision." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_draft_revision", "expected_published_version", "preview_receipt", "confirmed" ], "properties": { "expected_draft_revision": { "type": "string", "format": "date-time" }, "expected_published_version": { "type": "integer", "minimum": 0 }, "preview_receipt": { "type": "string", "minLength": 40, "maxLength": 2000 }, "confirmed": { "const": true } } } } } }, "responses": { "200": { "description": "New immutable published revision.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormsAuthoringForm" }, "meta": { "$ref": "#/components/schemas/FormsAuthoringMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form not found in this tenant." }, "409": { "description": "Idempotency, revision, receipt, or review-gate conflict." }, "428": { "description": "If-Match is required." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{id}/close": { "post": { "summary": "Stop collection without deleting history", "operationId": "closeForm", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "description": "Requires CLIENT_API_ENABLED=on, a registered client, and an owner-consented forms:lifecycle grant. Close remains available after module deactivation; history is retained.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"v1:[a-f0-9]{32}\"$" }, "description": "One current strong ETag. The body must also contain the current draft revision." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_draft_revision" ], "properties": { "expected_draft_revision": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Form closed; history retained.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormsAuthoringForm" }, "meta": { "$ref": "#/components/schemas/FormsAuthoringMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form not found in this tenant." }, "409": { "description": "Idempotency, revision, or lifecycle-state conflict." }, "428": { "description": "If-Match is required." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/schema.json": { "get": { "summary": "Read the Forms authoring structural schema", "operationId": "getFormsAuthoringSchema", "security": [ { "OAuth2": [ "front_desk:forms:read" ] }, { "OAuth2": [ "forms:lifecycle" ] } ], "description": "Requires CLIENT_API_ENABLED=on, a registered client, and a forms read or owner-consented forms:lifecycle grant. Structural checks only; POST /forms/validate runs the canonical semantic validator. The versioned Forms authoring OpenAPI companion (getFormsAuthoringContract) lives at GET /forms/openapi.json and is cross-linked here rather than duplicated.", "parameters": [], "responses": { "200": { "description": "Structural JSON Schema versioned in $comment.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{formId}/responses": { "get": { "summary": "List form responses with stable historical columns", "operationId": "listFormResponses", "description": "Newest-first tenant-scoped keyset page. The opaque cursor is bound to this form and the complete filter fingerprint; unknown query parameters are rejected.", "security": [ { "OAuth2": [ "forms:responses:read" ] } ], "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor issued for this exact form and filter." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated partial, completed, or spam states. Defaults to partial,completed." }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Inclusive YYYY-MM-DD in the tenant time zone or a full ISO timestamp." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "Exclusive YYYY-MM-DD in the tenant time zone or a full ISO timestamp; must follow from." }, { "name": "ending", "in": "query", "schema": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "description": "Ending reference from the form definition." }, { "name": "revision", "in": "query", "schema": { "type": "string" }, "description": "Published version number, or any." }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Free-text search over text, email, and phone answers only." }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "JSON-encoded array of at most 20 {ref, op, value} field predicates." }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "JSON-encoded {op, value} tag predicate." }, { "name": "owner_status", "in": "query", "schema": { "type": "string", "enum": [ "new", "in_review", "done" ] } }, { "name": "correction_state", "in": "query", "schema": { "type": "string", "enum": [ "corrected", "uncorrected" ] } } ], "responses": { "200": { "description": "Response page, filter definition, total count, and stable current-plus-historical column descriptors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponseCollection" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form not found in this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Historical revision, unknown-field, or stable-column reconstruction exceeds the public bound.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{formId}/responses/{responseId}": { "get": { "summary": "Read one form response", "operationId": "getFormResponse", "description": "Returns one tenant- and form-bound response with the same stable column descriptors as the list route. No query parameters are accepted.", "security": [ { "OAuth2": [ "forms:responses:read" ] } ], "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "responseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Response and stable current-plus-historical column descriptors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponseResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form or response not found in this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Historical revision, unknown-field, or stable-column reconstruction exceeds the public bound.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{formId}/analytics": { "get": { "summary": "Read revision-pinned form analytics", "operationId": "getFormAnalytics", "description": "Deterministic branch-aware analytics. Every metric includes its numerator, denominator, definition, and exclusions; synthetic responses are excluded. Only revision_id is accepted.", "security": [ { "OAuth2": [ "forms:analytics:read" ] } ], "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Immutable form revision to analyze." } ], "responses": { "200": { "description": "Revision-pinned analytics for at most 200 questions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormAnalyticsResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form revision not found in this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The revision exceeds the bounded analytics population.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{formId}/insights": { "get": { "summary": "List stored evidence-backed form insights", "operationId": "listStoredFormInsights", "description": "Reads unexpired tenant-owned insight artifacts with their source population fingerprint and row counts. It never invokes a model or creates a new insight.", "security": [ { "OAuth2": [ "forms:analytics:read" ] } ], "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Stored insight artifacts and evidence citations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoredFormInsight" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "limit": { "type": "integer" }, "generated_new_insight": { "const": false } }, "required": [ "request_id", "limit", "generated_new_insight" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form not found in this tenant." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{formId}/exports": { "post": { "summary": "Create an idempotent frozen form-response export", "operationId": "createFormResponseExport", "description": "Creates CSV or XLSX bytes from a response population and stable column manifest frozen in one transaction at request time. Unknown body, filter, and query keys are rejected.", "security": [ { "OAuth2": [ "exports:create" ] } ], "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,254}$" }, "description": "Durably bound to the tenant, grant, client, operation, path, and canonical request. Same request replays; different request returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormExportRequest" } } } }, "responses": { "202": { "description": "Frozen export created, or a completed idempotent response replayed.", "headers": { "Idempotency-Replayed": { "description": "true only when replaying the stored response.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormExportResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Form not found in this tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency key mismatch, concurrent in-flight request, or deterministic command conflict.", "headers": { "Retry-After": { "description": "Present while an equivalent request is still in flight.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The frozen manifest or export population exceeds the public bound.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Client API rate limit exceeded, or five exports are already queued or running for this tenant.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitError" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/forms/{formId}/exports/{exportId}": { "get": { "summary": "Read form export status", "operationId": "getFormResponseExport", "description": "Returns tenant-bound lifecycle and progress metadata only. No object keys, file bytes, download URLs, or query parameters.", "security": [ { "OAuth2": [ "exports:read" ] } ], "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "exportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current export metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormExportResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Export not found in this tenant and form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/{formId}/exports/{exportId}/download": { "get": { "summary": "Download a completed form export once", "operationId": "downloadFormResponseExport", "description": "Atomically consumes the export one-time download and returns CSV or XLSX bytes directly. The job must be ready, unexpired, and not previously downloaded; no permanent URL is returned.", "security": [ { "OAuth2": [ "exports:read" ] } ], "parameters": [ { "name": "formId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "exportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Completed attachment. A successful response consumes the one-time download.", "headers": { "Content-Disposition": { "description": "Server-generated attachment filename.", "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "text/csv": { "schema": { "type": "string", "contentMediaType": "text/csv" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Export not found in this tenant and form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Export is not ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Export expired or its one-time download was already consumed. Both use the generic not_found error body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/payments/deposit-capability": { "get": { "summary": "Read deposit-link capability state", "operationId": "getDepositCapability", "description": "Reports whether the business-owned deposit-link lane is configured. It never returns the payment URL, charges, refunds, or confirms settlement.", "security": [ { "OAuth2": [ "bookings:read" ] } ], "parameters": [], "responses": { "200": { "description": "Provider-free payment capability state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DepositCapability" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" } }, "required": [ "request_id" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/workflows/preview": { "post": { "summary": "Preview a bounded CRM workflow rule", "operationId": "previewCrmWorkflow", "description": "Validates and evaluates one closed workflow rule against exact supplied facts. The deterministic response includes an idempotency basis and never executes an action.", "security": [ { "OAuth2": [ "automations:read" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Deterministic preview-only evaluation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowPreview" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" } }, "required": [ "request_id" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/bookings": { "get": { "summary": "bookings", "operationId": "listbookings", "security": [ { "OAuth2": [ "bookings:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reviews": { "get": { "summary": "reviews", "operationId": "listreviews", "security": [ { "OAuth2": [ "reviews:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/client-accounts": { "get": { "summary": "client accounts", "operationId": "listclientaccounts", "security": [ { "OAuth2": [ "client_accounts:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientAccount" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "11111111-1111-4111-8111-111111111111", "name": "Northside Property Group", "status": "active" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/jobs": { "get": { "summary": "jobs", "operationId": "listjobs", "security": [ { "OAuth2": [ "jobs:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Optional UTC range start with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with to. The range may not exceed 366 days." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Optional UTC range end with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with from." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "22222222-2222-4222-8222-222222222222", "title": "Water heater repair", "status": "scheduled" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "summary": "Prepare one bounded asynchronous Client API job", "operationId": "createClientApiJob", "security": [ { "OAuth2": [ "jobs:write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientApiJobCreateRequest" } } } }, "responses": { "202": { "description": "Queued job status. Repeating the same idempotency key and request replays the same job.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientApiJobResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Idempotency key conflicts with a different request." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/jobs/{id}": { "get": { "summary": "Read one asynchronous Client API job", "operationId": "getClientApiJob", "security": [ { "OAuth2": [ "jobs:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant and grant-bound job status with an opaque result manifest.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientApiJobResource" } } } }, "304": { "description": "The job version has not changed.", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Job not found for this tenant and grant." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/jobs/{id}/cancel": { "post": { "summary": "Cancel one queued or running asynchronous job", "operationId": "cancelClientApiJob", "security": [ { "OAuth2": [ "jobs:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled job status.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientApiJobResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Job not found." }, "409": { "description": "The version or lifecycle state is no longer cancellable." }, "428": { "description": "If-Match is required." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/jobs/{id}/retry": { "post": { "summary": "Retry one retryable failed asynchronous job", "operationId": "retryClientApiJob", "security": [ { "OAuth2": [ "jobs:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Queued retry status.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientApiJobResource" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Job not found." }, "409": { "description": "The version or lifecycle state is not retryable." }, "428": { "description": "If-Match is required." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tasks": { "get": { "summary": "tasks", "operationId": "listtasks", "security": [ { "OAuth2": [ "tasks:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Optional UTC range start with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with to. The range may not exceed 366 days." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Optional UTC range end with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with from." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "33333333-3333-4333-8333-333333333333", "title": "Confirm access window", "status": "open" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/requests": { "get": { "summary": "requests", "operationId": "listrequests", "security": [ { "OAuth2": [ "requests:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Request" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "33333333-3333-4333-8333-333333333334", "summary": "Needs an estimate", "status": "open" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/requests/{requestId}": { "get": { "summary": "Read one Request with its bounded public conversation", "operationId": "getRequest", "security": [ { "OAuth2": [ "requests:read" ] } ], "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The tenant-owned Request and at most its latest 100 public messages.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/RequestDetail" }, "meta": { "type": "object", "additionalProperties": false, "required": [ "version" ], "properties": { "version": { "type": "string", "const": "1" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Request not found in this tenant." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/pipeline-opportunities": { "get": { "summary": "pipeline opportunities", "operationId": "listpipelineopportunities", "security": [ { "OAuth2": [ "pipeline_opportunities:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "pipeline_key", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 48 } } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineOpportunity" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "44444444-4444-4444-8444-444444444444", "pipeline_key": "sales", "stage_key": "qualified", "title": "Boiler replacement" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/activities": { "get": { "summary": "activities", "operationId": "listactivities", "security": [ { "OAuth2": [ "activities:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Optional UTC range start with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with to. The range may not exceed 366 days." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Optional UTC range end with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with from." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "55555555-5555-4555-8555-555555555555", "event_type": "job.changed", "occurred_at": "2026-08-26T12:00:00.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/saved-views": { "get": { "summary": "saved views", "operationId": "listsavedviews", "security": [ { "OAuth2": [ "saved_views:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Optional UTC range start with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with to. The range may not exceed 366 days." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Optional UTC range end with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with from." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SavedView" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "66666666-6666-4666-8666-666666666666", "key": "open_jobs", "label": "Open jobs", "resource": "jobs", "revision": 2 } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/saved-views/{id}/results": { "get": { "summary": "Run one saved view without changing it", "operationId": "runSavedView", "security": [ { "OAuth2": [ "saved_views:execute" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revision", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A source-revision-pinned saved-view result page.", "content": { "application/json": { "example": { "data": [ { "resource": "jobs", "record_id": "22222222-2222-4222-8222-222222222222", "display_label": "Water heater repair", "secondary_label": null, "state_label": "scheduled", "created_at": null, "updated_at": null } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "data_revision": "42", "saved_view": { "id": "66666666-6666-4666-8666-666666666666", "key": "open_jobs", "label": "Open jobs", "resource": "jobs", "revision": 2 } } }, "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": [ "string", "null" ] }, "record_id": { "type": [ "string", "null" ] }, "display_label": { "type": [ "string", "null" ] }, "secondary_label": { "type": [ "string", "null" ] }, "state_label": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "resource", "record_id", "display_label", "secondary_label", "state_label", "created_at", "updated_at" ] } }, "meta": { "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "data_revision": { "type": "string" }, "saved_view": { "$ref": "#/components/schemas/SavedView" } }, "required": [ "limit", "has_more", "next_cursor", "data_revision", "saved_view" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Saved view not found." }, "409": { "description": "Saved view revision changed." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/report-definitions": { "get": { "summary": "report definitions and latest successful runs", "operationId": "listreportdefinitionsandlatestsuccessfulruns", "security": [ { "OAuth2": [ "reports:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportDefinition" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "77777777-7777-4777-8777-777777777777", "version": 1, "name": "Open work by status", "resource": "jobs", "latest_successful_run": null } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/automation-executions": { "get": { "summary": "recent automation execution summaries", "operationId": "listrecentautomationexecutionsummaries", "security": [ { "OAuth2": [ "automations:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Optional UTC range start with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with to. The range may not exceed 366 days." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" }, "description": "Optional UTC range end with seconds and a Z suffix; optional fractional seconds have 1 to 3 digits. Supply with from." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationExecution" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "88888888-8888-4888-8888-888888888888", "rule_id": "99999999-9999-4999-8999-999999999999", "rule_version": 3, "status": "succeeded" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/dashboard": { "get": { "summary": "Dashboard overview", "operationId": "getDashboardOverview", "security": [ { "OAuth2": [ "dashboard:read" ] } ], "parameters": [], "responses": { "200": { "description": "A compact operational overview.", "content": { "application/json": { "example": { "data": { "business": { "name": "Acme Plumbing" }, "ai_employee": { "name": "Acme Assistant", "status": "active" }, "today": { "messages": 4, "voice_minutes": 12, "appointments": 1 }, "channels": { "messenger": false, "whatsapp": false, "instagram": false, "phone": true, "email": false, "calendar": true } } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "business": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } }, "required": [ "name" ] }, "ai_employee": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "required": [ "name", "status" ] }, "today": { "type": "object", "properties": { "messages": { "type": "number" }, "voice_minutes": { "type": "number" }, "appointments": { "type": "number" } }, "required": [ "messages", "voice_minutes", "appointments" ] }, "channels": { "type": "object", "properties": { "messenger": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "instagram": { "type": "boolean" }, "phone": { "type": "boolean" }, "email": { "type": "boolean" }, "calendar": { "type": "boolean" } }, "required": [ "messenger", "whatsapp", "instagram", "phone", "email", "calendar" ] } }, "required": [ "business", "ai_employee", "today", "channels" ] } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/events": { "get": { "summary": "API events", "operationId": "listAPIevents", "security": [ { "OAuth2": [ "events:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiEvent" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks": { "get": { "summary": "List verified webhook endpoints", "operationId": "listWebhookEndpoints", "security": [ { "OAuth2": [ "webhooks:manage" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "Tenant-scoped webhook endpoints.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "page": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "request_id", "version", "limit", "has_more", "next_cursor" ] } }, "required": [ "data", "page", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "summary": "Create a webhook endpoint and one-time verification challenge", "operationId": "createWebhookEndpoint", "security": [ { "OAuth2": [ "webhooks:manage" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url", "event_names" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "event_names": { "type": "array", "minItems": 1, "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "example": "signature.envelope.completed" } } } } } } }, "responses": { "201": { "description": "Endpoint, one-time signing secret, and verification challenge.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProvisionedWebhookEndpoint" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks/{id}": { "get": { "summary": "Read one webhook endpoint", "operationId": "getWebhookEndpoint", "security": [ { "OAuth2": [ "webhooks:manage" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Endpoint not found." }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "summary": "Remove one webhook endpoint", "operationId": "deleteWebhookEndpoint", "security": [ { "OAuth2": [ "webhooks:manage" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Endpoint removed." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Endpoint not found." }, "409": { "description": "Endpoint lifecycle conflict." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks/{id}/verify": { "post": { "summary": "Verify and activate a webhook endpoint", "operationId": "verifyWebhookEndpoint", "security": [ { "OAuth2": [ "webhooks:manage" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "challenge" ], "properties": { "challenge": { "type": "string", "minLength": 32, "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Verified active endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Endpoint not found." }, "409": { "description": "Challenge expired, replayed, or raced." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhook-deliveries": { "get": { "summary": "List sanitized webhook delivery status", "operationId": "listWebhookDeliveries", "security": [ { "OAuth2": [ "webhook_deliveries:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "endpoint_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "leased", "failed_retryable", "delivered", "dead_letter" ] } } ], "responses": { "200": { "description": "Tenant-scoped delivery metadata with a sanitized latest attempt; event payloads, endpoint URLs, signing material, provider bodies, and lease identities are never returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "page": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "request_id", "version", "limit", "has_more", "next_cursor" ] } }, "required": [ "data", "page", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhook-deliveries/{id}": { "get": { "summary": "Read sanitized webhook delivery attempt history", "operationId": "getWebhookDelivery", "security": [ { "OAuth2": [ "webhook_deliveries:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "One tenant-scoped delivery and at most 50 sanitized settled attempts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookDeliveryDetail" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Delivery not found." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/tasks": { "get": { "summary": "CRM tasks", "operationId": "listCRMtasks", "security": [ { "OAuth2": [ "tasks:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "status", "in": "query", "schema": { "enum": [ "open", "done", "canceled" ] } }, { "name": "contact_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "job_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "overdue", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "true selects open tasks past due; combining it with a non-open status is refused. false applies no overdue filter." }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Optional comma-separated selection: id, title, description, status, priority, due_at, contact_id, job_id, owner, completed_at, created_at, updated_at, revision." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmTask" } }, "page": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "request_id", "version", "limit", "has_more", "next_cursor" ] } }, "required": [ "data", "page", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/tasks/{id}": { "get": { "summary": "Read one CRM task", "operationId": "getCrmTask", "security": [ { "OAuth2": [ "tasks:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Optional comma-separated selection: id, title, description, status, priority, due_at, contact_id, job_id, owner, completed_at, created_at, updated_at, revision." } ], "responses": { "200": { "description": "Tenant-owned task with a strong ETag.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmTask" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Task not found." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/tasks/actions/create/preview": { "post": { "summary": "Preview one CRM task creation", "operationId": "previewCrmTaskCreate", "security": [ { "OAuth2": [ "tasks:prepare" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateInput" } } } }, "responses": { "200": { "description": "Exact no-effect preview and commit key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TaskCreatePreview" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/tasks/actions/create/commit": { "post": { "summary": "Commit one reviewed CRM task creation", "operationId": "commitCrmTaskCreate", "security": [ { "OAuth2": [ "tasks:commit" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "title", "preview_key", "confirmed" ], "properties": { "title": { "$ref": "#/components/schemas/TaskCreateInput/properties/title" }, "description": { "$ref": "#/components/schemas/TaskCreateInput/properties/description" }, "due_at": { "$ref": "#/components/schemas/TaskCreateInput/properties/due_at" }, "priority": { "$ref": "#/components/schemas/TaskCreateInput/properties/priority" }, "contact_id": { "$ref": "#/components/schemas/TaskCreateInput/properties/contact_id" }, "job_id": { "$ref": "#/components/schemas/TaskCreateInput/properties/job_id" }, "owner": { "$ref": "#/components/schemas/TaskCreateInput/properties/owner" }, "preview_key": { "type": "string", "minLength": 16, "maxLength": 200 }, "confirmed": { "const": true } } } } } }, "responses": { "201": { "description": "Task created once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmTask" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "outcome": { "type": "string" } }, "required": [ "request_id", "version", "outcome" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Preview or idempotency conflict." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/tasks/{id}/actions/status/preview": { "post": { "summary": "Preview a CRM task open or done transition", "operationId": "previewCrmTaskStatus", "security": [ { "OAuth2": [ "tasks:prepare" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStatusInput" } } } }, "responses": { "200": { "description": "Exact no-effect status preview, ETag, and commit key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TaskStatusPreview" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Task not found." }, "409": { "description": "Task revision or state conflict." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/tasks/{id}/actions/status/commit": { "post": { "summary": "Commit a reviewed CRM task status transition", "operationId": "commitCrmTaskStatus", "security": [ { "OAuth2": [ "tasks:commit" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 256 } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "target_status", "expected_revision", "preview_key", "confirmed" ], "properties": { "target_status": { "$ref": "#/components/schemas/TaskStatusInput/properties/target_status" }, "expected_revision": { "$ref": "#/components/schemas/TaskStatusInput/properties/expected_revision" }, "preview_key": { "type": "string", "minLength": 16, "maxLength": 200 }, "confirmed": { "const": true } } } } } }, "responses": { "200": { "description": "Task status changed once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmTask" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "outcome": { "type": "string" } }, "required": [ "request_id", "version", "outcome" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Preview, state, revision, or idempotency conflict." }, "428": { "description": "If-Match is required." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/document-templates": { "get": { "summary": "document templates", "operationId": "listdocumenttemplates", "security": [ { "OAuth2": [ "documents:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentTemplate" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/document-templates/{id}": { "get": { "summary": "Read one document template", "operationId": "getDocumentTemplate", "security": [ { "OAuth2": [ "documents:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template and immutable version layouts without storage identifiers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocumentTemplate" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Template not found." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/signature-envelopes": { "get": { "summary": "signature envelopes", "operationId": "listsignatureenvelopes", "security": [ { "OAuth2": [ "signatures:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." } ], "responses": { "200": { "description": "A tenant-scoped page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SignatureEnvelope" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/signature-envelopes/{id}": { "get": { "summary": "Read one signature envelope status", "operationId": "getSignatureEnvelope", "security": [ { "OAuth2": [ "signatures:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Envelope lifecycle and retention status without recipients, signer tokens, fields, evidence details, artifacts, storage identifiers, or actor labels.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SignatureEnvelope" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "304": { "description": "The version-derived ETag still matches.", "headers": { "ETag": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Envelope not found." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/exports": { "get": { "summary": "List every available portability dataset", "operationId": "listExportDatasets", "security": [ { "OAuth2": [ "exports:read" ] } ], "parameters": [], "responses": { "200": { "description": "The complete field-allowlisted CSV export catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCatalog" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/exports/{dataset}.csv": { "get": { "summary": "Stream one complete tenant dataset as CSV", "operationId": "downloadExportDataset", "security": [ { "OAuth2": [ "exports:read" ] } ], "parameters": [ { "name": "dataset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "calls", "call-insight-reviews", "callers", "lead-lifecycle-history", "lead-reason-sets", "lead-import-history", "chats", "messages", "webchat-resolution-feedback", "taken-messages", "bookings", "internal-calendar-events", "reviews", "client-accounts", "account-relationships", "account-command-history", "jobs", "fulfillment-operations", "fulfillment-outbox", "call-outcomes", "call-outcome-steps", "equipment", "equipment-service-history", "equipment-service-evidence", "job-status-links", "delivery-templates", "delivery-plans", "delivery-items", "delivery-dependencies", "delivery-blockers", "delivery-history", "tasks", "task-reminders", "task-reminder-deliveries", "team-workload-revision", "team-queues", "team-queue-memberships", "team-queue-resources", "team-queue-watchers", "task-assignment-history", "resource-assignment-history", "team-threads", "team-messages", "team-mentions", "team-notifications", "team-notification-preferences", "push-devices", "team-command-history", "crm-activity", "crm-timeline", "business-files", "business-file-sources", "business-file-revisions", "business-file-publications", "intake-media", "attachments", "signature-envelopes", "signature-recipients", "signature-fields", "signature-field-values", "signature-events", "signature-artifacts", "signature-templates", "signature-verifications", "signature-bulk-batches", "signature-bulk-items", "sales-pipeline-definitions", "sales-opportunities", "sales-opportunity-history", "crm-duplicate-candidates", "crm-duplicate-dismissed-pairs", "crm-forecast-snapshots", "crm-import-mapping-profiles", "crm-import-dry-run-fingerprints", "sla-policies", "sla-ticket-clocks", "sla-ticket-clock-pauses", "crm-account-classifications", "crm-account-segments", "csat-survey-definitions", "csat-survey-invitations", "csat-survey-responses", "crm-relationship-edges", "territories", "territory-visit-events", "portal-access-grants", "config-draft-versions", "config-activations", "crm-partner-account-attributes", "crm-partner-contacts", "crm-partner-onboarding-events", "crm-partner-lead-registrations", "crm-partner-lead-events", "crm-contact-identities", "crm-contact-merge-aliases", "tenant-referrals", "tenant-referral-events", "incentive-plan-versions", "incentive-period-versions", "incentive-period-participants", "incentive-revenue-credits", "incentive-revenue-credit-splits", "incentive-adjustments", "incentive-statements", "crm-layout-visibility-conditions", "crm-layout-approved-actions", "crm-report-definitions", "crm-report-runs", "crm-report-result-rows", "crm-report-memberships", "crm-report-command-history", "custom-field-definitions", "custom-field-values", "custom-field-definition-history", "custom-field-value-history", "custom-field-command-history", "record-layout-history", "customer-cases", "customer-case-messages", "customer-case-events", "customer-case-reply-snippets", "service-area-settings", "public-faqs", "faq-disclosures", "consented-visitor-activity", "saved-views", "search-saved-views", "quote-templates", "settings" ] }, "description": "Dataset id returned by GET /exports." } ], "responses": { "200": { "description": "A UTF-8 CSV attachment streamed in bounded-memory pages.", "content": { "text/csv": { "schema": { "type": "string", "contentMediaType": "text/csv" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The dataset id is not part of the export catalog." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/forms/openapi.json": { "get": { "operationId": "getFormsAuthoringContract", "summary": "Read the Forms authoring OpenAPI contract", "security": [ { "OAuth2": [ "front_desk:forms:read" ] } ], "parameters": [], "responses": { "200": { "description": "The Forms OpenAPI 3.1 companion document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/notes": { "get": { "operationId": "listCrmNotes", "summary": "List append-only notes for one CRM subject", "security": [ { "OAuth2": [ "activities:read" ] } ], "description": "Requires the activity module. Both subject filters are mandatory; this is not a tenant-wide note scan. Results are ordered by created_at and id descending. Cursors are bound to the tenant and subject filters.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "subject_type", "in": "query", "required": true, "schema": { "enum": [ "contact", "job", "task" ] } }, { "name": "subject_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Optional comma-separated selection: id, subject_type, subject_id, body, actor, created_at." } ], "responses": { "200": { "description": "Tenant-scoped note page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmNote" } }, "page": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "request_id", "version", "limit", "has_more", "next_cursor" ] } }, "required": [ "data", "page", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/notes/actions/create/preview": { "post": { "operationId": "previewCrmNoteCreate", "summary": "Preview an append-only CRM note", "security": [ { "OAuth2": [ "activities:write" ] } ], "parameters": [], "description": "Requires the Client API launch gate, configured CRM cursor/preview secret, and the tenant module entitlement. Preview has no side effects. Commit requires explicit confirmation of the sealed preview and never sends messages, places calls, or synchronizes a provider.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmNoteCreateInput" } } } }, "responses": { "200": { "description": "Tenant-scoped reviewed CRM result.", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmNoteCreatePreview" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The resource or referenced subject is not available in this tenant." }, "409": { "description": "Preview expired, grant binding changed, state changed, or idempotency key conflicted." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/notes/actions/create/commit": { "post": { "operationId": "commitCrmNoteCreate", "summary": "Append an explicitly reviewed CRM note", "security": [ { "OAuth2": [ "activities:write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "description": "Reuse the same key and receipt to replay a successful commit. Receipts are retained for 24 hours." } ], "description": "Requires the Client API launch gate, configured CRM cursor/preview secret, and the tenant module entitlement. Preview has no side effects. Commit requires explicit confirmation of the sealed preview and never sends messages, places calls, or synchronizes a provider.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewedCrmCommit" } } } }, "responses": { "201": { "description": "Tenant-scoped reviewed CRM result.", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmNote" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "outcome": { "const": "create" }, "mutation_policy": { "type": "string" } }, "required": [ "request_id", "version", "outcome", "mutation_policy" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The resource or referenced subject is not available in this tenant." }, "409": { "description": "Preview expired, grant binding changed, state changed, or idempotency key conflicted." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/jobs": { "get": { "operationId": "listCrmJobs", "summary": "List CRM business jobs", "security": [ { "OAuth2": [ "jobs:read" ] } ], "description": "Requires the jobs module. These business records are distinct from asynchronous /jobs. Results are ordered by updated_at and id descending; cursors are tenant- and filter-bound.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor returned in meta.next_cursor. Cursor semantics are resource-specific; deduplicate by resource id and reconcile from the first page after a long export." }, { "name": "status", "in": "query", "schema": { "enum": [ "lead", "quoted", "scheduled", "in_progress", "done", "closed", "cancelled", "lost" ] } }, { "name": "contact_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Optional comma-separated selection: id, contact_id, status, title, details, service_name, source_channel, lifecycle_stage, qualification, owner, quoted_at, scheduled_at, started_at, completed_at, created_at, updated_at." } ], "responses": { "200": { "description": "Tenant-scoped CRM job page.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmJob" } }, "page": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ] }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "request_id", "version", "limit", "has_more", "next_cursor" ] } }, "required": [ "data", "page", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/jobs/{id}": { "get": { "operationId": "getCrmJob", "summary": "Read one CRM business job", "security": [ { "OAuth2": [ "jobs:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Optional comma-separated selection: id, contact_id, status, title, details, service_name, source_channel, lifecycle_stage, qualification, owner, quoted_at, scheduled_at, started_at, completed_at, created_at, updated_at." } ], "responses": { "200": { "description": "CRM job and strong ETag.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmJob" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The resource or referenced subject is not available in this tenant." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/jobs/actions/create/preview": { "post": { "operationId": "previewCrmJobCreate", "summary": "Preview a CRM business job creation", "security": [ { "OAuth2": [ "jobs:write" ] } ], "parameters": [], "description": "Requires the Client API launch gate, configured CRM cursor/preview secret, and the tenant module entitlement. Preview has no side effects. Commit requires explicit confirmation of the sealed preview and never sends messages, places calls, or synchronizes a provider.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmJobCreateInput" } } } }, "responses": { "200": { "description": "Tenant-scoped reviewed CRM result.", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmJobCreatePreview" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The resource or referenced subject is not available in this tenant." }, "409": { "description": "Preview expired, grant binding changed, state changed, or idempotency key conflicted." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/jobs/actions/create/commit": { "post": { "operationId": "commitCrmJobCreate", "summary": "Create an explicitly reviewed CRM business job", "security": [ { "OAuth2": [ "jobs:write" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "description": "Reuse the same key and receipt to replay a successful commit. Receipts are retained for 24 hours." } ], "description": "Requires the Client API launch gate, configured CRM cursor/preview secret, and the tenant module entitlement. Preview has no side effects. Commit requires explicit confirmation of the sealed preview and never sends messages, places calls, or synchronizes a provider.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewedCrmCommit" } } } }, "responses": { "201": { "description": "Tenant-scoped reviewed CRM result.", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmJob" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "outcome": { "type": "string" } }, "required": [ "request_id", "version", "outcome" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The resource or referenced subject is not available in this tenant." }, "409": { "description": "Preview expired, grant binding changed, state changed, or idempotency key conflicted." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/jobs/{id}/actions/lifecycle/preview": { "post": { "operationId": "previewCrmJobLifecycle", "summary": "Preview a permitted CRM job status transition", "security": [ { "OAuth2": [ "jobs:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Current strong ETag from GET /crm/jobs/{id}." } ], "description": "Requires the Client API launch gate, configured CRM cursor/preview secret, and the tenant module entitlement. Preview has no side effects. Commit requires explicit confirmation of the sealed preview and never sends messages, places calls, or synchronizes a provider.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "enum": [ "lead", "quoted", "scheduled", "in_progress", "done", "closed", "cancelled", "lost" ] } }, "required": [ "to" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Exact before/after status and a sealed 15-minute receipt. The server enforces the allowed transition graph.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmJobLifecyclePreview" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "required": [ "request_id", "version" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The resource or referenced subject is not available in this tenant." }, "409": { "description": "Preview expired, grant binding changed, state changed, or idempotency key conflicted." }, "428": { "description": "If-Match is required." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/crm/jobs/{id}/actions/lifecycle/commit": { "post": { "operationId": "commitCrmJobLifecycle", "summary": "Commit an explicitly reviewed CRM job status transition", "security": [ { "OAuth2": [ "jobs:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "description": "Reuse the same key and receipt to replay a successful commit. Receipts are retained for 24 hours." } ], "description": "Requires the Client API launch gate, configured CRM cursor/preview secret, and the tenant module entitlement. Preview has no side effects. Commit requires explicit confirmation of the sealed preview and never sends messages, places calls, or synchronizes a provider.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewedCrmCommit" } } } }, "responses": { "200": { "description": "Tenant-scoped reviewed CRM result.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmJob" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "version": { "const": "1" }, "outcome": { "type": "string" } }, "required": [ "request_id", "version", "outcome" ] } }, "required": [ "data", "meta" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The resource or referenced subject is not available in this tenant." }, "409": { "description": "Preview expired, grant binding changed, state changed, or idempotency key conflicted." }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "OAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.firstaiemployee.com/oauth/authorize", "tokenUrl": "https://api.firstaiemployee.com/oauth/token", "scopes": { "calls:read": "Read call history, summaries and transcripts.", "contacts:read": "Read callers and their recorded consent state.", "contacts:write": "Create and update callers through the CRM contact preview and commit flow.", "front_desk:forms:read": "Read Forms metadata and draft definitions.", "forms:write": "Edit and save Forms drafts directly under revision and idempotency controls.", "forms:lifecycle": "Create, duplicate, preview, publish, close, and delete empty never-published form drafts under owner consent.", "forms:responses:read": "Read bounded form responses and stable current-plus-historical column descriptors.", "forms:analytics:read": "Read deterministic, revision-pinned, branch-aware form analytics.", "bookings:read": "Read booking records.", "reviews:read": "Read reviews and reply status.", "exports:create": "Create frozen form-response exports under durable idempotency.", "exports:read": "Read and download frozen form exports, and download field-allowlisted tenant portability datasets.", "client_accounts:read": "Read client account summaries.", "jobs:read": "Read job summaries.", "tasks:read": "Read task summaries.", "requests:read": "Read Requests and their bounded public conversations.", "pipeline_opportunities:read": "Read opportunities in one published pipeline.", "activities:read": "Read the source-backed CRM activity timeline.", "activities:write": "Preview and commit append-only CRM notes as the authorized OAuth grant.", "jobs:write": "Preview and commit bounded native CRM job creation and lifecycle changes.", "saved_views:read": "Read saved CRM view definitions and presentation summaries.", "saved_views:execute": "Run a saved CRM view without changing it.", "reports:read": "Read report definitions and each latest successful run.", "automations:read": "Read recent automation execution summaries.", "dashboard:read": "Read a compact Front Desk dashboard overview.", "events:read": "Read bounded tenant-scoped API event history.", "webhooks:manage": "Create, verify, inspect, and remove webhook endpoints.", "webhook_deliveries:read": "Read sanitized webhook delivery status and attempt history.", "documents:read": "Read document templates and immutable version layouts.", "signatures:read": "Read signature envelope lifecycle status without signer-sensitive details.", "tasks:prepare": "Preview bounded CRM task creation and status changes.", "tasks:commit": "Commit only reviewed CRM task creation and status changes." } } } } }, "responses": { "BadRequest": { "description": "Invalid request parameters or body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, invalid, expired or revoked bearer token.", "headers": { "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The bearer grant lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Client API ingress or verified client-and-tenant rate exceeded. Honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": [ "string", "null" ] } } } } }, "RateLimitError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "PageMeta": { "type": "object", "required": [ "limit", "has_more", "next_cursor" ], "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "Call": { "type": "object", "required": [ "id", "occurred_at", "caller" ], "properties": { "id": { "type": "string", "format": "uuid" }, "occurred_at": { "type": [ "string", "null" ] }, "caller": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } } }, "duration_seconds": { "type": [ "integer", "null" ] }, "outcome": { "type": [ "string", "null" ] }, "intent": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ] }, "services_mentioned": { "type": [ "string", "null" ] }, "follow_up_needed": { "type": [ "boolean", "null" ] }, "spam_status": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "transcript": { "type": [ "string", "null" ] } } }, "Contact": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "tags": {}, "classification": { "type": [ "string", "null" ] }, "total_jobs": { "type": [ "integer", "null" ] }, "lifetime_value": {}, "consent": { "type": "object" }, "first_seen_at": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ] }, "lead_source": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "qualification": { "type": "string" } } }, "CrmContactInput": { "type": "object", "additionalProperties": false, "required": [ "phone" ], "properties": { "phone": { "type": "string", "minLength": 1, "maxLength": 50 }, "email": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 } } }, "CrmContact": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "classification": { "type": [ "string", "null" ] }, "total_jobs": { "type": "integer" }, "lifetime_value": { "type": [ "string", "null" ] }, "consent": { "type": "object" }, "first_seen_at": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "lead_source": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "qualification": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 } } }, "Form": { "type": "object", "required": [ "id", "ref", "title", "status", "version", "draft_revision" ], "properties": { "id": { "type": "string", "format": "uuid" }, "ref": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "definition": { "type": "object" }, "version": { "type": "integer" }, "received_responses": { "type": "integer" }, "draft_revision": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "published_at": { "type": [ "string", "null" ] } } }, "FormResponseColumn": { "type": "object", "additionalProperties": false, "required": [ "ref", "title", "type", "removed", "unknownHistory" ], "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "removed": { "type": "boolean", "description": "True when the current definition no longer carries this question." }, "unknownHistory": { "type": "boolean", "description": "True when no referenced revision can recover its label and field type." } } }, "FormResponse": { "type": "object", "additionalProperties": false, "required": [ "id", "formId", "formVersion", "revisionId", "revisionFingerprint", "status", "answers", "hidden", "calculated", "ending", "landedAt", "submittedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "formId": { "type": "string", "format": "uuid" }, "formVersion": { "type": "integer", "minimum": 1 }, "revisionId": { "type": [ "string", "null" ], "format": "uuid" }, "revisionFingerprint": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "partial", "completed", "spam" ] }, "answers": { "type": "object", "additionalProperties": true, "description": "Answers keyed by field reference. File answers omit storage keys and permanent URLs. Signature acknowledgments carry the safe completion projection only: kind, optional printed name, completion, and time. The typed mark, drawn storage id, signer email, and statement text never leave the response-storage boundary." }, "hidden": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "calculated": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Allowlisted warnings, logic result, mode result, and clarification prompts only." }, "ending": { "type": [ "string", "null" ] }, "landedAt": { "type": [ "string", "null" ], "format": "date-time" }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "FormResponseListMeta": { "type": "object", "required": [ "request_id", "version", "limit", "has_more", "next_cursor", "total", "filter_fingerprint", "filter_description", "column_descriptor_fingerprint", "columns" ], "properties": { "request_id": { "type": "string" }, "version": { "type": "string", "const": "1" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0 }, "filter_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "filter_description": { "type": "string" }, "column_descriptor_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "columns": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/FormResponseColumn" } } } }, "FormResponseCollection": { "type": "object", "additionalProperties": false, "required": [ "data", "page", "meta" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/FormResponse" } }, "page": { "type": "object", "additionalProperties": false, "required": [ "next_cursor", "has_more" ], "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/FormResponseListMeta" } } }, "FormResponseResource": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormResponse" }, "meta": { "type": "object", "required": [ "request_id", "version", "column_descriptor_fingerprint", "columns" ], "properties": { "request_id": { "type": "string" }, "version": { "type": "string", "const": "1" }, "column_descriptor_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "columns": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/FormResponseColumn" } } } } } }, "FormAnalyticsExclusions": { "type": "object", "additionalProperties": false, "required": [ "input", "spam", "synthetic", "included", "policy" ], "properties": { "input": { "type": "integer", "minimum": 0 }, "spam": { "type": "integer", "minimum": 0 }, "synthetic": { "type": "integer", "minimum": 0 }, "included": { "type": "integer", "minimum": 0 }, "policy": { "type": "string" } } }, "FormAnalyticsMetric": { "type": "object", "additionalProperties": false, "required": [ "value", "numerator", "denominator", "definition", "exclusions" ], "properties": { "value": { "type": [ "number", "string", "null" ] }, "numerator": { "type": "number" }, "denominator": { "type": "number" }, "definition": { "type": "string" }, "exclusions": { "$ref": "#/components/schemas/FormAnalyticsExclusions" } } }, "FormAnalyticsDistribution": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "count" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "count": { "$ref": "#/components/schemas/FormAnalyticsMetric" } } }, "FormAnalyticsProfileComparison": { "type": "object", "additionalProperties": false, "required": [ "ref", "title", "wins", "mean_score" ], "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "wins": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "mean_score": { "$ref": "#/components/schemas/FormAnalyticsMetric" } } }, "FormAnalyticsAggregate": { "type": "object", "required": [ "kind" ], "description": "Choice uses options/none; boolean uses true/false/none; numeric uses count/mean/median/min/max; NPS adds promoters/passives/detractors/score; date uses min/max; text and presence use answered/skipped.", "properties": { "kind": { "type": "string", "enum": [ "choice", "boolean", "numeric", "nps", "date", "text", "presence" ] }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/FormAnalyticsDistribution" } }, "none": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "true": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "false": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "count": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "mean": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "median": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "min": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "max": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "promoters": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "passives": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "detractors": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "score": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "answered": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "skipped": { "$ref": "#/components/schemas/FormAnalyticsMetric" } } }, "FormAnalyticsQuestion": { "type": "object", "additionalProperties": false, "required": [ "ref", "title", "type", "eligible", "reached", "answered", "skipped", "abandoned_at", "aggregate" ], "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "eligible": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "reached": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "answered": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "skipped": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "abandoned_at": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "aggregate": { "$ref": "#/components/schemas/FormAnalyticsAggregate" } } }, "FormAnalytics": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "revision_id", "exclude_synthetic", "exclusions", "questions", "endings", "outcomes", "profile_comparison", "qualification" ], "properties": { "schema_version": { "type": "integer", "const": 1 }, "revision_id": { "type": "string", "format": "uuid" }, "exclude_synthetic": { "type": "boolean", "const": true }, "exclusions": { "$ref": "#/components/schemas/FormAnalyticsExclusions" }, "questions": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/FormAnalyticsQuestion" } }, "endings": { "type": "array", "items": { "$ref": "#/components/schemas/FormAnalyticsDistribution" } }, "outcomes": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/FormAnalyticsDistribution" } }, { "type": "null" } ] }, "profile_comparison": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/FormAnalyticsProfileComparison" } }, { "type": "null" } ], "description": "Declared-order personality/recommendation profile wins and mean scores. Null when the revision declares no profiles." }, "qualification": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "qualified", "unqualified", "unknown" ], "properties": { "qualified": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "unqualified": { "$ref": "#/components/schemas/FormAnalyticsMetric" }, "unknown": { "$ref": "#/components/schemas/FormAnalyticsMetric" } } }, { "type": "null" } ] } } }, "FormAnalyticsResource": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormAnalytics" }, "meta": { "type": "object", "required": [ "request_id", "version" ], "properties": { "request_id": { "type": "string" }, "version": { "type": "string", "const": "1" } } } } }, "FormResponseFieldPredicate": { "type": "object", "required": [ "ref", "op" ], "properties": { "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "op": { "type": "string", "enum": [ "contains", "not_contains", "starts_with", "equals", "is", "is_not", "any_of", "all_of", "eq", "gt", "gte", "lt", "lte", "between", "before", "after", "last_n_days", "answered", "not_answered" ] }, "value": { "description": "Scalar, two-value range, or choice-reference array as required by the field type and operator." } } }, "FormResponseFilter": { "type": "object", "additionalProperties": false, "properties": { "status": { "oneOf": [ { "type": "string" }, { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "partial", "completed", "spam" ] } } ] }, "from": { "type": "string" }, "to": { "type": "string" }, "ending": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "revision": { "oneOf": [ { "type": "string", "const": "any" }, { "type": "string", "pattern": "^[1-9][0-9]*$" }, { "type": "integer", "minimum": 1 } ] }, "q": { "type": "string", "maxLength": 200 }, "fields": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/FormResponseFieldPredicate" } }, "tag": { "type": "object", "required": [ "op", "value" ], "properties": { "op": { "type": "string", "enum": [ "has_tag", "not_has_tag" ] }, "value": { "type": "string", "maxLength": 40 } } }, "owner_status": { "type": "string", "enum": [ "new", "in_review", "done" ] }, "correction_state": { "type": "string", "enum": [ "corrected", "uncorrected" ] } } }, "FormExportRequest": { "type": "object", "additionalProperties": false, "description": "Omitted format defaults to CSV; omitted filter uses the default non-spam population.", "properties": { "format": { "type": "string", "enum": [ "csv", "xlsx" ], "default": "csv" }, "filter": { "$ref": "#/components/schemas/FormResponseFilter" } } }, "FormExport": { "type": "object", "additionalProperties": false, "required": [ "id", "format", "status", "filterFingerprint", "descriptorFingerprint", "revisionScope", "progressRows", "rowCount", "error", "downloaded", "expiresAt", "createdAt", "percent" ], "properties": { "id": { "type": "string", "format": "uuid" }, "format": { "type": "string", "enum": [ "csv", "xlsx" ] }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "cancelled", "failed", "expired" ] }, "filterFingerprint": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "descriptorFingerprint": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "revisionScope": { "type": "string" }, "progressRows": { "type": "integer", "minimum": 0 }, "rowCount": { "type": "integer", "minimum": 0 }, "error": { "type": [ "string", "null" ] }, "downloaded": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Expires 24 hours after creation." }, "createdAt": { "type": "string", "format": "date-time" }, "percent": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } } }, "FormExportResource": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/FormExport" }, "meta": { "type": "object", "required": [ "request_id", "version" ], "properties": { "request_id": { "type": "string" }, "version": { "type": "string", "const": "1" }, "filter_description": { "type": "string", "description": "Present on creation and describes the frozen population." } } } } }, "ApiEvent": { "type": "object", "required": [ "id", "name", "occurred_at", "payload" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object" } } }, "Booking": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } } }, "Review": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": [ "string", "null" ] }, "author_name": { "type": [ "string", "null" ] }, "rating": { "type": [ "integer", "null" ] }, "text": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ] }, "topic": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reply": { "type": "object" } } }, "ClientAccount": { "type": "object", "required": [ "id", "name", "status" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "version": { "type": [ "integer", "null" ] }, "kind": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "owner": { "type": "object" }, "rollup": { "type": "object" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "ClientApiJob": { "type": "object", "additionalProperties": false, "required": [ "id", "operation", "state", "progress", "retryable", "attempt", "max_attempts", "version", "created_at", "updated_at", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "operation": { "type": "string", "enum": [ "form_export", "ai_insight", "report_run", "integration_sync" ] }, "state": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "cancelled", "expired" ] }, "progress": { "type": "object", "additionalProperties": false, "required": [ "completed", "total" ], "properties": { "completed": { "type": "integer", "minimum": 0, "maximum": 1000 }, "total": { "type": "integer", "minimum": 0, "maximum": 1000 } } }, "result_manifest": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "item_count": { "type": "integer", "minimum": 0, "maximum": 20 }, "byte_count": { "type": "integer", "minimum": 0, "maximum": 52428800 }, "result_ref": { "type": "string", "pattern": "^result_[A-Za-z0-9_-]{16,128}$" } } }, "error_code": { "type": [ "string", "null" ] }, "retryable": { "type": "boolean" }, "attempt": { "type": "integer", "minimum": 0, "maximum": 3 }, "max_attempts": { "type": "integer", "minimum": 1, "maximum": 3 }, "version": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "ClientApiJobResource": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ClientApiJob" }, "meta": { "type": "object", "additionalProperties": false, "required": [ "request_id", "version" ], "properties": { "request_id": { "type": "string" }, "version": { "type": "string", "const": "1" } } } } }, "ClientApiJobCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "operation", "total", "expires_at", "approved" ], "properties": { "operation": { "type": "string", "enum": [ "form_export", "ai_insight", "report_run", "integration_sync" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 1000 }, "expires_at": { "type": "string", "format": "date-time" }, "approved": { "const": true }, "retryable": { "type": "boolean" }, "max_attempts": { "type": "integer", "minimum": 1, "maximum": 3 } } }, "Job": { "type": "object", "required": [ "id", "title", "status" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "string", "null" ] }, "client_account_id": { "type": [ "string", "null" ] }, "service_name": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "accepted_quote_total_cents": { "type": [ "integer", "null" ] }, "source_channel": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "Task": { "type": "object", "required": [ "id", "title", "status" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "revision": { "type": [ "integer", "null" ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "string", "null" ] }, "job_id": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "RequestOwner": { "type": "object", "additionalProperties": false, "required": [ "kind", "team_member_id" ], "properties": { "kind": { "type": "string", "enum": [ "unassigned", "owner", "team_member" ] }, "team_member_id": { "type": [ "string", "null" ] } } }, "Request": { "type": "object", "additionalProperties": false, "required": [ "id", "contact_id", "job_id", "source", "summary", "category", "priority", "status", "owner", "tags", "revision", "responded_at", "resolved_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "job_id": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "summary": { "type": "string" }, "category": { "type": "string" }, "priority": { "type": "string" }, "status": { "type": "string" }, "owner": { "$ref": "#/components/schemas/RequestOwner" }, "tags": { "type": "array", "items": { "type": "string" } }, "revision": { "type": "integer", "minimum": 1 }, "responded_at": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RequestConversationItem": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "text", "created_at", "author" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "customer_message", "public_reply" ] }, "text": { "type": "string", "maxLength": 4000 }, "created_at": { "type": "string", "format": "date-time" }, "author": { "type": "string", "enum": [ "customer", "business" ] } } }, "RequestDetail": { "type": "object", "additionalProperties": false, "required": [ "id", "contact_id", "job_id", "source", "summary", "category", "priority", "status", "owner", "tags", "revision", "responded_at", "resolved_at", "created_at", "updated_at", "description", "conversation" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "job_id": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "summary": { "type": "string" }, "category": { "type": "string" }, "priority": { "type": "string" }, "status": { "type": "string" }, "owner": { "$ref": "#/components/schemas/RequestOwner" }, "tags": { "type": "array", "items": { "type": "string" } }, "revision": { "type": "integer", "minimum": 1 }, "responded_at": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "conversation": { "type": "object", "additionalProperties": false, "required": [ "items", "truncated" ], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/RequestConversationItem" } }, "truncated": { "type": "boolean" } } } } }, "TaskCreateInput": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high" ] }, "contact_id": { "type": [ "string", "null" ] }, "job_id": { "type": [ "string", "null" ] }, "owner": { "type": "object" } } }, "TaskStatusInput": { "type": "object", "additionalProperties": false, "required": [ "target_status", "expected_revision" ], "properties": { "target_status": { "type": "string", "enum": [ "open", "done" ] }, "expected_revision": { "type": "integer", "minimum": 1 } } }, "DocumentTemplate": { "type": "object", "required": [ "id", "name", "kind", "status", "versions" ], "properties": { "id": { "type": "string", "format": "uuid" }, "form_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "active_version_id": { "type": [ "string", "null" ] }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentTemplateVersion" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SignatureEnvelope": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "status", "title", "document_kind", "related_record", "delivery_method", "legal_hold", "retention_policy", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "sent", "in_progress", "finalizing", "completed", "declined", "voided", "expired", "finalization_failed", "abandoned" ] }, "title": { "type": "string" }, "document_kind": { "type": "string", "enum": [ "agreement", "quote_acceptance" ] }, "related_record": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "business", "contact", "account", "job", "task" ] }, "id": { "type": "string", "format": "uuid" } }, "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind" ], "properties": { "kind": { "type": "string", "const": "business" } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "id" ], "properties": { "kind": { "type": "string", "enum": [ "contact", "account", "job", "task" ] }, "id": { "type": "string", "format": "uuid" } } } ] }, "delivery_method": { "type": "string", "enum": [ "copy_link", "email" ] }, "legal_hold": { "type": "boolean" }, "retention_policy": { "type": "string", "enum": [ "90_days", "1_year", "3_years", "7_years" ] }, "retention_until": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PipelineOpportunity": { "type": "object", "required": [ "id", "pipeline_key", "stage_key", "title" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "version": { "type": [ "integer", "null" ] }, "pipeline_key": { "type": [ "string", "null" ] }, "stage_key": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "value_cents": { "type": [ "integer", "null" ] }, "expected_close_date": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "string", "null" ] }, "job_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "Activity": { "type": "object", "required": [ "id", "event_type", "occurred_at" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "event_type": { "type": [ "string", "null" ] }, "payload": { "type": "object" }, "actor": { "type": "object" }, "subjects": { "type": "array", "items": { "type": "object" } }, "occurred_at": { "type": [ "string", "null" ] }, "record": { "type": [ "object", "null" ] } } }, "SavedView": { "type": "object", "required": [ "id", "key", "label", "resource", "revision" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "key": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "resource": { "type": [ "string", "null" ] }, "revision": { "type": [ "integer", "null" ] }, "presentation": { "type": "object" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "ReportDefinition": { "type": "object", "required": [ "id", "version", "name", "resource" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "version": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "resource": { "type": [ "string", "null" ] }, "dimensions": { "type": "array" }, "measures": { "type": "array" }, "date_range": { "type": "object" }, "archived_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "latest_successful_run": { "type": [ "object", "null" ] } } }, "AutomationExecution": { "type": "object", "required": [ "id", "rule_id", "rule_version", "status" ], "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "rule_id": { "type": [ "string", "null" ] }, "rule_version": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ] }, "attempt_count": { "type": [ "integer", "null" ] }, "maximum_attempts": { "type": [ "integer", "null" ] }, "event_label": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "next_retry_at": { "type": [ "string", "null" ] }, "last_error_code": { "type": [ "string", "null" ] }, "actions": { "type": "array", "items": { "type": "object" } }, "subject": { "type": "object" } } }, "CrmJob": { "type": "object", "properties": { "id": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "status": { "enum": [ "lead", "quoted", "scheduled", "in_progress", "done", "closed", "cancelled", "lost" ] }, "title": { "type": "string" }, "details": { "type": [ "string", "null" ] }, "service_name": { "type": [ "string", "null" ] }, "source_channel": { "type": [ "string", "null" ] }, "lifecycle_stage": { "type": "string" }, "qualification": { "type": "string" }, "owner": { "type": "object", "properties": { "kind": { "type": "string" }, "team_member_id": { "type": [ "string", "null" ] } }, "required": [ "kind", "team_member_id" ] }, "quoted_at": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [], "description": "Tenant-owned CRM business job, distinct from the asynchronous /jobs resource. fields can select any subset of these properties." }, "CrmNote": { "type": "object", "properties": { "id": { "type": "string" }, "subject_type": { "enum": [ "contact", "job", "task" ] }, "subject_id": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "actor": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] } }, "required": [ "email", "role" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id" ], "description": "Append-only CRM note. fields may select a subset; id is always included. Mutation responses return all listed fields." }, "ReviewedCrmCommit": { "type": "object", "properties": { "preview_token": { "type": "string", "minLength": 32, "maxLength": 8192 }, "confirmed": { "const": true } }, "required": [ "preview_token", "confirmed" ], "additionalProperties": false }, "CrmJobCreateInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Trimmed; whitespace-only titles are refused." }, "details": { "type": [ "string", "null" ], "maxLength": 20000 }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "service_name": { "type": [ "string", "null" ], "maxLength": 80 }, "status": { "enum": [ "lead", "quoted", "scheduled", "in_progress", "done", "closed", "cancelled", "lost" ], "default": "lead", "description": "Must also satisfy the current job creation policy." } }, "required": [ "title" ], "additionalProperties": false }, "CrmNoteCreateInput": { "type": "object", "properties": { "subject_type": { "enum": [ "contact", "job", "task" ] }, "subject_id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Trimmed; blank notes are refused." } }, "required": [ "subject_type", "subject_id", "body" ], "additionalProperties": false }, "CrmJobCreatePreview": { "type": "object", "properties": { "operation": { "const": "job.create" }, "before": { "type": "null" }, "after": { "type": "object", "properties": { "title": { "type": "string" }, "details": { "type": [ "string", "null" ] }, "contactId": { "type": [ "string", "null" ] }, "serviceName": { "type": [ "string", "null" ] }, "status": { "enum": [ "lead", "quoted", "scheduled", "in_progress", "done", "closed", "cancelled", "lost" ] } }, "required": [ "title", "details", "contactId", "serviceName", "status" ] }, "commit": { "$ref": "#/components/schemas/ReviewedCrmPreviewReceipt" }, "non_effects": { "type": "array", "items": { "type": "string" } } }, "required": [ "operation", "before", "after", "commit", "non_effects" ] }, "CrmJobLifecyclePreview": { "type": "object", "properties": { "operation": { "const": "job.lifecycle" }, "before": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "version" ] }, "after": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ] }, "commit": { "$ref": "#/components/schemas/ReviewedCrmPreviewReceipt" }, "non_effects": { "type": "array", "items": { "type": "string" } } }, "required": [ "operation", "before", "after", "commit", "non_effects" ] }, "CrmNoteCreatePreview": { "type": "object", "properties": { "operation": { "const": "note.create" }, "before": { "type": "null" }, "after": { "type": "object", "properties": { "subject_type": { "type": "string" }, "subject_id": { "type": "string" }, "body": { "type": "string" }, "actor": { "type": "object", "properties": { "kind": { "const": "oauth_grant" }, "grant_id": { "type": [ "string", "null" ] }, "client_id": { "type": [ "string", "null" ] } }, "required": [ "kind", "grant_id", "client_id" ] } }, "required": [ "subject_type", "subject_id", "body", "actor" ] }, "commit": { "$ref": "#/components/schemas/ReviewedCrmPreviewReceipt" }, "non_effects": { "type": "array", "items": { "type": "string" } } }, "required": [ "operation", "before", "after", "commit", "non_effects" ] }, "ReviewedCrmPreviewReceipt": { "type": "object", "properties": { "preview_token": { "type": "string", "description": "Sealed, expiring receipt bound to this tenant and OAuth grant. Do not log it or substitute edited fields at commit." }, "expires_at": { "type": "string", "format": "date-time" }, "requires_confirmation": { "const": true } }, "required": [ "preview_token", "expires_at", "requires_confirmation" ] }, "DocumentTemplateVersion": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "is_active": { "type": "boolean" }, "source_pdf_configured": { "type": "boolean" }, "version_fingerprint": { "type": "string" }, "merge_placements": { "type": "array", "items": { "type": "object", "properties": { "placement_ref": { "type": "string" }, "source_kind": { "type": "string" }, "source_ref": { "type": "string" }, "page": { "type": "integer" }, "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" }, "font": { "type": "string" }, "font_size": { "type": "number" }, "alignment": { "type": "string" }, "line_limit": { "type": "integer" }, "overflow_policy": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "placement_ref", "source_kind", "source_ref", "page", "x", "y", "w", "h", "font", "font_size", "alignment", "line_limit", "overflow_policy", "required" ] } }, "signature_placements": { "type": "array", "items": { "type": "object", "properties": { "placement_ref": { "type": "string" }, "recipient_role_ref": { "type": "string" }, "field_type": { "type": "string" }, "page": { "type": "integer" }, "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" }, "required": { "type": "boolean" } }, "required": [ "placement_ref", "recipient_role_ref", "field_type", "page", "x", "y", "w", "h", "required" ] } }, "approved_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "status", "is_active", "source_pdf_configured", "version_fingerprint", "merge_placements", "signature_placements", "approved_at", "created_at", "updated_at" ] }, "ApiDiscovery": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "read_only": { "type": "boolean" }, "resources": { "type": "object", "additionalProperties": { "type": "string" } }, "granted_scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "version", "read_only", "resources", "granted_scopes" ] }, "CurrentClient": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "business_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "time_zone": { "type": [ "string", "null" ] }, "oauth_client_id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "business_name", "email", "time_zone", "oauth_client_id", "scopes" ] } }, "required": [ "data" ] }, "OpenApiDocument": { "type": "object", "required": [ "openapi", "info", "paths" ], "properties": { "openapi": { "const": "3.1.0" }, "info": { "type": "object", "properties": { "title": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" } }, "required": [ "title", "version", "description" ] }, "servers": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } }, "paths": { "type": "object" }, "components": { "type": "object" }, "security": { "type": "array", "items": { "type": "object" } } }, "description": "An OpenAPI 3.1 document. Path items and components follow the OpenAPI specification." }, "ContactUpsertPreview": { "type": "object", "properties": { "kind": { "enum": [ "create", "update", "no_op", "ambiguous", "conflict" ] }, "contact_id": { "type": [ "string", "null" ] }, "before": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [] }, "after": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [] }, "expected_revision": { "type": [ "integer", "null" ] }, "non_effects": { "type": "array", "items": { "type": "string" } }, "candidate_ids": { "type": "array", "items": { "type": "string" } }, "ambiguity": { "type": "string" }, "refusal": { "type": "string" }, "reason": { "type": "string" }, "commit": { "type": "object", "properties": { "committable": { "type": "boolean" }, "preview_key": { "type": "string" }, "expected_revision": { "type": [ "integer", "null" ] }, "if_match_required": { "type": "boolean" }, "etag": { "type": [ "string", "null" ] }, "idempotency_key_header": { "type": "string" }, "confirmation_required": { "type": "boolean" } }, "required": [ "committable", "preview_key", "expected_revision", "if_match_required" ] } }, "required": [ "kind", "contact_id", "before", "after", "expected_revision", "non_effects", "commit" ] }, "CrmTask": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "priority": { "type": "string" }, "due_at": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "string", "null" ] }, "job_id": { "type": [ "string", "null" ] }, "owner": { "type": "object", "properties": { "kind": { "type": "string" }, "team_member_id": { "type": [ "string", "null" ] } }, "required": [ "kind", "team_member_id" ] }, "completed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "revision": { "type": "integer" } }, "required": [ "id" ], "description": "The CRM task projection. fields may select a subset; id is always returned. Mutation responses return all listed properties." }, "TaskCreatePreview": { "type": "object", "properties": { "kind": { "type": "string" }, "before": { "type": "object", "properties": { "title": { "type": "null" }, "due_at": { "type": "null" }, "priority": { "type": "null" }, "owner": { "type": "null" } }, "required": [ "title", "due_at", "priority", "owner" ] }, "after": { "type": "object", "properties": { "title": { "type": "string" }, "due_at": { "type": [ "string", "null" ] }, "priority": { "type": "string" }, "owner": { "type": "object", "properties": { "kind": { "type": "string" }, "team_member_id": { "type": [ "string", "null" ] } }, "required": [ "kind", "team_member_id" ] }, "description": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "string", "null" ] }, "job_id": { "type": [ "string", "null" ] } }, "required": [ "title", "due_at", "priority", "owner", "description", "contact_id", "job_id" ] }, "expected_revision": { "type": "null" }, "non_effects": { "type": "array", "items": { "type": "string" } }, "commit": { "type": "object", "properties": { "committable": { "type": "boolean" }, "preview_key": { "type": "string" }, "expected_revision": { "type": [ "integer", "null" ] }, "if_match_required": { "type": "boolean" }, "etag": { "type": [ "string", "null" ] }, "idempotency_key_header": { "type": "string" }, "confirmation_required": { "type": "boolean" } }, "required": [ "committable", "preview_key", "expected_revision", "if_match_required" ] } }, "required": [ "kind", "before", "after", "expected_revision", "non_effects", "commit" ] }, "TaskStatusPreview": { "type": "object", "properties": { "kind": { "type": "string" }, "task_id": { "type": "string" }, "before": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "after": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "expected_revision": { "type": "integer" }, "non_effects": { "type": "array", "items": { "type": "string" } }, "commit": { "type": "object", "properties": { "committable": { "type": "boolean" }, "preview_key": { "type": "string" }, "expected_revision": { "type": [ "integer", "null" ] }, "if_match_required": { "type": "boolean" }, "etag": { "type": [ "string", "null" ] }, "idempotency_key_header": { "type": "string" }, "confirmation_required": { "type": "boolean" } }, "required": [ "committable", "preview_key", "expected_revision", "if_match_required" ] } }, "required": [ "kind", "task_id", "before", "after", "expected_revision", "non_effects", "commit" ] }, "FormScheduling": { "type": "object", "properties": { "form_id": { "type": "string" }, "source": { "const": "draft" }, "scheduling_fields": { "type": "array", "items": { "type": "object", "properties": { "field_ref": { "type": "string" }, "title": { "type": "string" }, "provider": { "type": "string" }, "duration_minutes": { "type": "integer" }, "buffer_minutes": { "type": "integer" }, "max_days_ahead": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "working_hours_source": { "type": "string" } }, "required": [ "field_ref", "title", "provider", "duration_minutes", "buffer_minutes", "max_days_ahead", "weekdays", "working_hours_source" ] } }, "provider_availability_queried": { "const": false }, "booking_created": { "const": false } }, "required": [ "form_id", "source", "scheduling_fields", "provider_availability_queried", "booking_created" ] }, "StoredFormInsight": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "evidence": { "type": "object", "properties": { "filter_fingerprint": { "type": "string" }, "filter_summary": { "type": "string" }, "population_rows": { "type": "integer" }, "rows_read": { "type": "integer" }, "window_from": { "type": [ "string", "null" ] }, "window_to": { "type": [ "string", "null" ] } }, "required": [ "filter_fingerprint", "filter_summary", "population_rows", "rows_read", "window_from", "window_to" ] }, "generated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "question", "answer", "evidence", "generated_at", "expires_at" ] }, "DepositCapability": { "type": "object", "properties": { "capability": { "const": "business_owned_deposit_link" }, "enabled": { "type": "boolean" }, "ready": { "type": "boolean" }, "mode": { "type": [ "string", "null" ] }, "unavailable_reason": { "type": [ "string", "null" ] }, "trigger": { "type": "string" }, "charge_supported": { "const": false }, "refund_supported": { "const": false }, "provider_settlement_confirmed": { "const": false }, "payment_url_disclosed": { "const": false } }, "required": [ "capability", "enabled", "ready", "mode", "unavailable_reason", "trigger", "charge_supported", "refund_supported", "provider_settlement_confirmed", "payment_url_disclosed" ] }, "WorkflowPreview": { "type": "object", "properties": { "contractVersion": { "type": "string" }, "mode": { "const": "preview_only" }, "status": { "type": "string" }, "ruleKey": { "type": "string" }, "ruleVersion": { "type": "integer" }, "ruleStatus": { "type": "string" }, "ruleFingerprint": { "type": "string" }, "eventFingerprint": { "type": "string" }, "idempotencyBasis": { "type": "string" }, "triggerMatched": { "type": "boolean" }, "conditionsMatched": { "type": "boolean" }, "wouldMatch": { "type": "boolean" }, "humanApprovalRequired": { "type": "boolean" }, "actionPreviews": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "type": { "type": "string" }, "approvalRequirement": { "type": "string" }, "decision": { "type": "string" } }, "required": [ "index", "type", "approvalRequirement", "decision" ] } }, "conditionTrace": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "fact": { "type": "string" }, "operator": { "type": "string" }, "expected": { "type": [ "string", "boolean", "number" ] }, "actual": { "type": [ "string", "boolean", "number", "null" ] }, "matched": { "type": "boolean" }, "reason": { "enum": [ "matched", "not_matched", "missing_fact" ] } }, "required": [ "path", "fact", "operator", "expected", "actual", "matched", "reason" ] } }, "executionPerformed": { "const": false }, "executionAllowed": { "const": false } }, "required": [ "contractVersion", "mode", "status", "ruleKey", "ruleVersion", "ruleStatus", "ruleFingerprint", "eventFingerprint", "idempotencyBasis", "triggerMatched", "conditionsMatched", "wouldMatch", "humanApprovalRequired", "actionPreviews", "conditionTrace", "executionPerformed", "executionAllowed" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "event_names": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "verification_status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "event_names", "status", "verification_status", "created_at", "updated_at" ] }, "ProvisionedWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "event_names": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "verification_status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "signing_secret": { "type": "string", "description": "Returned only on creation. Store securely; subsequent reads cannot recover this value." }, "verification_challenge": { "type": "string" }, "verification_expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "event_names", "status", "verification_status", "created_at", "updated_at", "signing_secret", "verification_challenge", "verification_expires_at" ] }, "WebhookDeliveryAttempt": { "type": "object", "properties": { "attempt": { "type": "integer" }, "state": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "latency_ms": { "type": "integer" }, "http_status": { "type": [ "integer", "null" ] }, "error_code": { "type": [ "string", "null" ] } }, "required": [ "attempt", "state", "started_at", "finished_at", "latency_ms", "http_status", "error_code" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_id": { "type": "string" }, "event": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "occurred_at" ] }, "state": { "type": "string" }, "attempt_count": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ] }, "latest_attempt": { "anyOf": [ { "$ref": "#/components/schemas/WebhookDeliveryAttempt" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ] }, "dead_lettered_at": { "type": [ "string", "null" ] } }, "required": [ "id", "endpoint_id", "event", "state", "attempt_count", "next_attempt_at", "latest_attempt", "created_at", "updated_at", "delivered_at", "dead_lettered_at" ] }, "WebhookDeliveryDetail": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_id": { "type": "string" }, "event": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "occurred_at" ] }, "state": { "type": "string" }, "attempt_count": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ] }, "latest_attempt": { "anyOf": [ { "$ref": "#/components/schemas/WebhookDeliveryAttempt" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ] }, "dead_lettered_at": { "type": [ "string", "null" ] }, "attempts": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/WebhookDeliveryAttempt" } } }, "required": [ "id", "endpoint_id", "event", "state", "attempt_count", "next_attempt_at", "latest_attempt", "created_at", "updated_at", "delivered_at", "dead_lettered_at", "attempts" ] }, "ExportCatalog": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "enum": [ "calls", "call-insight-reviews", "callers", "lead-lifecycle-history", "lead-reason-sets", "lead-import-history", "chats", "messages", "webchat-resolution-feedback", "taken-messages", "bookings", "internal-calendar-events", "reviews", "client-accounts", "account-relationships", "account-command-history", "jobs", "fulfillment-operations", "fulfillment-outbox", "call-outcomes", "call-outcome-steps", "equipment", "equipment-service-history", "equipment-service-evidence", "job-status-links", "delivery-templates", "delivery-plans", "delivery-items", "delivery-dependencies", "delivery-blockers", "delivery-history", "tasks", "task-reminders", "task-reminder-deliveries", "team-workload-revision", "team-queues", "team-queue-memberships", "team-queue-resources", "team-queue-watchers", "task-assignment-history", "resource-assignment-history", "team-threads", "team-messages", "team-mentions", "team-notifications", "team-notification-preferences", "push-devices", "team-command-history", "crm-activity", "crm-timeline", "business-files", "business-file-sources", "business-file-revisions", "business-file-publications", "intake-media", "attachments", "signature-envelopes", "signature-recipients", "signature-fields", "signature-field-values", "signature-events", "signature-artifacts", "signature-templates", "signature-verifications", "signature-bulk-batches", "signature-bulk-items", "sales-pipeline-definitions", "sales-opportunities", "sales-opportunity-history", "crm-duplicate-candidates", "crm-duplicate-dismissed-pairs", "crm-forecast-snapshots", "crm-import-mapping-profiles", "crm-import-dry-run-fingerprints", "sla-policies", "sla-ticket-clocks", "sla-ticket-clock-pauses", "crm-account-classifications", "crm-account-segments", "csat-survey-definitions", "csat-survey-invitations", "csat-survey-responses", "crm-relationship-edges", "territories", "territory-visit-events", "portal-access-grants", "config-draft-versions", "config-activations", "crm-partner-account-attributes", "crm-partner-contacts", "crm-partner-onboarding-events", "crm-partner-lead-registrations", "crm-partner-lead-events", "crm-contact-identities", "crm-contact-merge-aliases", "tenant-referrals", "tenant-referral-events", "incentive-plan-versions", "incentive-period-versions", "incentive-period-participants", "incentive-revenue-credits", "incentive-revenue-credit-splits", "incentive-adjustments", "incentive-statements", "crm-layout-visibility-conditions", "crm-layout-approved-actions", "crm-report-definitions", "crm-report-runs", "crm-report-result-rows", "crm-report-memberships", "crm-report-command-history", "custom-field-definitions", "custom-field-values", "custom-field-definition-history", "custom-field-value-history", "custom-field-command-history", "record-layout-history", "customer-cases", "customer-case-messages", "customer-case-events", "customer-case-reply-snippets", "service-area-settings", "public-faqs", "faq-disclosures", "consented-visitor-activity", "saved-views", "search-saved-views", "quote-templates", "settings" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "format": { "const": "text/csv" }, "endpoint": { "type": "string" } }, "required": [ "id", "label", "description", "format", "endpoint" ] } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" } }, "required": [ "count" ] } }, "required": [ "data", "meta" ] }, "FormsAuthoringDefinition": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.firstaiemployee.com/api/client/v1/forms/schema.json", "$comment": "Contract version 2026-09-05.1", "title": "Forms authoring document", "type": "object", "required": [ "title", "fields" ], "description": "Structural checks only. POST /forms/validate runs the canonical semantic validator. Saving also checks references, logic, settings and owned assets. Validation never authorizes publication.", "additionalProperties": true, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "fields": { "type": "array", "items": { "type": "object", "required": [ "type", "title" ], "additionalProperties": true, "properties": { "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "type": { "type": "string", "enum": [ "short_text", "long_text", "email", "phone_number", "multiple_choice", "checkbox", "picture_choice", "dropdown", "yes_no", "opinion_scale", "rating", "nps", "number", "date", "time", "address", "website", "file_upload", "signature", "contact", "ranking", "matrix", "scheduler", "statement", "legal" ] }, "title": { "type": "string" } } } }, "theme": { "type": "object", "description": "The canonical validator checks colors, layout, fonts and tenant-owned image references." } } }, "FormsAuthoringCreate": { "type": "object", "additionalProperties": false, "required": [ "definition" ], "properties": { "definition": { "$ref": "#/components/schemas/FormsAuthoringDefinition" }, "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" } } }, "FormsAuthoringDuplicate": { "type": "object", "additionalProperties": false, "required": [ "ref", "expected_draft_revision" ], "properties": { "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } } }, "FormsAuthoringPreview": { "type": "object", "additionalProperties": false, "required": [ "expected_draft_revision", "expected_published_version" ], "properties": { "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "expected_published_version": { "type": "integer", "minimum": 0 } } }, "FormsAuthoringPublish": { "type": "object", "additionalProperties": false, "required": [ "expected_draft_revision", "expected_published_version", "preview_receipt", "confirmed" ], "properties": { "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "expected_published_version": { "type": "integer", "minimum": 0 }, "preview_receipt": { "type": "string", "minLength": 40, "maxLength": 2000 }, "confirmed": { "const": true } } }, "FormsAuthoringConditionalWrite": { "type": "object", "additionalProperties": false, "required": [ "expected_draft_revision" ], "properties": { "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } } }, "FormsAuthoringValidate": { "type": "object", "additionalProperties": false, "required": [ "definition" ], "properties": { "definition": { "$ref": "#/components/schemas/FormsAuthoringDefinition" } } }, "FormsAuthoringApply": { "type": "object", "additionalProperties": false, "required": [ "version", "expected_draft_revision", "operations" ], "properties": { "version": { "const": 1 }, "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "operations": { "type": "array", "items": { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string" } } }, "description": "The closed operation vocabulary and semantic constraints are enforced by the canonical Forms operation parser." } } }, "FormsAuthoringMeta": { "type": "object", "required": [ "request_id", "version" ], "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "additionalProperties": true }, "FormsAuthoringForm": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "title": { "type": "string" }, "status": { "enum": [ "draft", "published", "closed" ] }, "version": { "type": "integer" }, "draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "definition": { "$ref": "#/components/schemas/FormsAuthoringDefinition" }, "received_responses": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] } } }, "FormsAuthoringPreparedPreview": { "type": "object", "required": [ "preview_receipt", "definition", "fingerprint", "expires_at", "expected_draft_revision", "expected_published_version", "published" ], "properties": { "preview_receipt": { "type": "string" }, "definition": { "$ref": "#/components/schemas/FormsAuthoringDefinition" }, "fingerprint": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "expected_published_version": { "type": "integer" }, "published": { "const": false }, "confirmation_instruction": { "type": "string" } } }, "FormsAuthoringDeleted": { "type": "object", "additionalProperties": false, "required": [ "id", "deleted", "scope" ], "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "const": true }, "scope": { "const": "never_published_empty_draft" } } }, "FormsAuthoringValidation": { "type": "object", "properties": { "definition": { "$ref": "#/components/schemas/FormsAuthoringDefinition" }, "warnings": { "type": "array" }, "publication_authorized": { "const": false }, "validation_scope": { "const": "definition_only" } } }, "FormsAuthoringApplied": { "type": "object", "properties": { "form": { "$ref": "#/components/schemas/FormsAuthoringForm" }, "applied": { "type": "object" }, "diff": { "type": "object" }, "warnings": { "type": "array" } } }, "FormsAuthoringError": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "retryable": { "type": "boolean" }, "field": { "type": [ "string", "null" ] }, "details": { "type": "object" } } } } } } } }