{
    "openapi": "3.0.3",
    "info": {
        "title": "RizzDial API",
        "description": "RizzDial API documentation \u00e2\u20ac\u201d Authentication, Dialer, AI Agents, Contacts, Dashboard & Widget endpoints.",
        "version": "1.0.0",
        "contact": {
            "name": "RizzDial Support"
        }
    },
    "servers": [
        {
            "url": "/",
            "description": "Current Server"
        }
    ],
    "components": {
        "securitySchemes": {
            "BearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "Passport Token",
                "description": "Use the token from /api/login or /api/dialer-login"
            }
        },
        "schemas": {
            "LoginRequest": {
                "type": "object",
                "required": [
                    "email",
                    "password"
                ],
                "properties": {
                    "email": {
                        "type": "string",
                        "example": "user@example.com"
                    },
                    "password": {
                        "type": "string",
                        "example": "secret123"
                    }
                }
            },
            "PaginationMeta": {
                "type": "object",
                "properties": {
                    "total": {
                        "type": "integer"
                    },
                    "current_page": {
                        "type": "integer"
                    },
                    "per_page": {
                        "type": "integer"
                    },
                    "last_page": {
                        "type": "integer"
                    },
                    "from": {
                        "type": "integer",
                        "nullable": true
                    },
                    "to": {
                        "type": "integer",
                        "nullable": true
                    }
                }
            },
            "SuccessResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "type": "object"
                    }
                }
            },
            "ErrorResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": false
                    },
                    "message": {
                        "type": "string"
                    }
                }
            },
            "DateRangeFilter": {
                "type": "string",
                "enum": [
                    "Today",
                    "Yesterday",
                    "Last 7 Days",
                    "Last 14 Days",
                    "Last 30 Days",
                    "This Month",
                    "Last Month",
                    "This Week Sun",
                    "This Week Mon",
                    "Last Week Sun",
                    "Last Week Mon",
                    "Last Business Week",
                    "Last Year"
                ],
                "default": "Today"
            },
            "CreatePhoneCallRequest": {
                "type": "object",
                "required": [
                    "phone_number"
                ],
                "properties": {
                    "phone_number": {
                        "type": "string",
                        "example": "+12137771235",
                        "description": "Destination number in E.164 format."
                    },
                    "call_mode": {
                        "type": "string",
                        "enum": [
                            "outbound",
                            "inbound"
                        ],
                        "example": "outbound",
                        "description": "outbound (default) places the call. inbound registers the call and returns dialSip so telephony can bridge the caller. Same JSON body for both."
                    },
                    "first_name": {
                        "type": "string",
                        "example": "John",
                        "description": "Optional contact field passed through with the call."
                    },
                    "last_name": {
                        "type": "string",
                        "example": "Doe"
                    },
                    "override_agent_id": {
                        "type": "string",
                        "nullable": true,
                        "description": "Use a different agent for this call only."
                    },
                    "ghl_contact_id": {
                        "type": "string",
                        "nullable": true,
                        "description": "Optional CRM contact id attached to the call."
                    },
                    "local_presence_number": {
                        "type": "string",
                        "enum": [
                            "Yes",
                            "No"
                        ],
                        "example": "No",
                        "description": "If Yes, outbound is placed from a local presence number."
                    }
                },
                "additionalProperties": {
                    "type": "string",
                    "description": "Any other contact field from GET /api/ai/agent/call-endpoint form_data."
                }
            },
            "CreateAgentRequest": {
                "type": "object",
                "properties": {
                    "agent_name": {
                        "type": "string",
                        "nullable": true,
                        "example": "Sales Agent",
                        "description": "Optional. If empty, a random agent name is generated like the dashboard create flow."
                    },
                    "general_prompt": {
                        "type": "string",
                        "nullable": true,
                        "example": "You are a sales assistant...",
                        "description": "Optional. Dashboard defaults are used during agent creation."
                    },
                    "weebhook_endpoint": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "weebhook_endpoint_method": {
                        "type": "string",
                        "enum": [
                            "GET",
                            "POST"
                        ],
                        "nullable": true
                    }
                }
            },
            "UpdateAgentRequest": {
                "type": "object",
                "example": {
                    "agent_name": "Updated Sales Agent",
                    "status": "Active",
                    "folder_id": "MQ==",
                    "ai_timezone_id": "NQ=="
                },
                "properties": {
                    "agent_name": {
                        "type": "string",
                        "example": "Updated Sales Agent",
                        "description": "Agent display name (also synced to voice provider)"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "Active",
                            "Inactive"
                        ],
                        "example": "Active",
                        "description": "Agent status"
                    },
                    "folder_id": {
                        "type": "string",
                        "example": "MQ==",
                        "nullable": true,
                        "description": "Base64 encoded folder ID (from GET /api/ai/agent/folders). Send null to remove agent from folder."
                    },
                    "ai_timezone_id": {
                        "nullable": true,
                        "description": "Timezone for the agent (General tab). Prefer the base64 string `id` from GET /api/ai/agent/timezones (same as the web UI list). A plain positive integer is also accepted. JSON must send base64 as a quoted string, e.g. `\"ai_timezone_id\": \"NQ==\"`.",
                        "oneOf": [
                            {
                                "type": "string",
                                "example": "NQ==",
                                "description": "Base64-encoded timezone id from List AI Agent Timezones (recommended)"
                            },
                            {
                                "type": "integer",
                                "example": 5,
                                "description": "Numeric timezone id (legacy)"
                            }
                        ]
                    }
                }
            },
            "UpdatePromptRequest": {
                "type": "object",
                "required": [
                    "agentId",
                    "prompt_mode",
                    "general_prompt"
                ],
                "properties": {
                    "agentId": {
                        "type": "string",
                        "example": "agent_abc123",
                        "description": "AI agent_id (from List AI Agents API)"
                    },
                    "prompt_mode": {
                        "type": "string",
                        "enum": [
                            "single",
                            "sectioned"
                        ],
                        "example": "sectioned",
                        "description": "single: only general_prompt is used, section fields are ignored. sectioned: general_prompt plus any filled section fields are concatenated. If general_prompt is a full headed prompt (=== Title ===, ## Title:, #Title#), those headings are split into the matching section fields automatically. Explicit section fields you send are kept."
                    },
                    "general_prompt": {
                        "type": "string",
                        "example": "You are a sales assistant...",
                        "description": "Main project instructions (required in both modes). In sectioned mode this may also be a full multi-section prompt; recognized headings (Project Instructions, Greeting Phrases, Character, Transfer Call Instructions, Script, Appt Booking Flow For GHL, FAQ / Objection Handling, Booking flow, CALL HANDLING RULES, and their aliases) are split into the matching fields."
                    },
                    "prompt_name": {
                        "type": "string",
                        "nullable": true,
                        "example": "My Sales Prompt",
                        "description": "Optional saved prompt name. Defaults to API_Update."
                    },
                    "prompt_greetings": {
                        "type": "string",
                        "nullable": true,
                        "description": "Greeting phrases section (only used when prompt_mode = sectioned)"
                    },
                    "prompt_character": {
                        "type": "string",
                        "nullable": true,
                        "description": "Character / persona section (only used when prompt_mode = sectioned)"
                    },
                    "prompt_critical_instr": {
                        "type": "string",
                        "nullable": true,
                        "description": "Critical instructions / guardrails section (only used when prompt_mode = sectioned)"
                    },
                    "prompt_transfer_instr": {
                        "type": "string",
                        "nullable": true,
                        "description": "Transfer instructions section (only used when prompt_mode = sectioned)"
                    },
                    "prompt_custom_vars": {
                        "type": "string",
                        "nullable": true,
                        "description": "Allowed custom variables section (only used when prompt_mode = sectioned)"
                    },
                    "prompt_company_info": {
                        "type": "string",
                        "nullable": true,
                        "description": "Company info section (only used when prompt_mode = sectioned)"
                    },
                    "prompt_script_flow": {
                        "type": "string",
                        "nullable": true,
                        "description": "Script flow section (only used when prompt_mode = sectioned)"
                    },
                    "prompt_call_flow": {
                        "type": "string",
                        "nullable": true,
                        "description": "Call flow section (only used when prompt_mode = sectioned)"
                    },
                    "prompt_objections": {
                        "type": "string",
                        "nullable": true,
                        "description": "Common objections & responses section (only used when prompt_mode = sectioned)"
                    },
                    "prompt_appt_flow": {
                        "type": "string",
                        "nullable": true,
                        "description": "Appointment booking flow section (only used when prompt_mode = sectioned)"
                    },
                    "prompt_faq_base": {
                        "type": "string",
                        "nullable": true,
                        "description": "FAQ / knowledge base section (only used when prompt_mode = sectioned)"
                    },
                    "save_mode": {
                        "type": "string",
                        "enum": [
                            "copy",
                            "override"
                        ],
                        "nullable": true,
                        "example": "copy",
                        "description": "Same as dashboard prompt save mode. Use override with selected_prompt_id to replace a saved prompt."
                    },
                    "selected_prompt_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "NQ==",
                        "description": "Base64 prompt ID from prompt history, or a numeric ID, used when save_mode is override."
                    },
                    "apply_to_agent_ids": {
                        "type": "array",
                        "nullable": true,
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "agent_other_123"
                        ],
                        "description": "Optional AI agent_ids that should receive the same prompt. Use GET /api/ai/agent/prompt/apply-agents for this dropdown."
                    }
                }
            },
            "UpdateSavedPromptRequest": {
                "type": "object",
                "properties": {
                    "prompt_name": {
                        "type": "string",
                        "example": "My Sales Prompt",
                        "description": "New name for this saved prompt"
                    },
                    "prompt_mode": {
                        "type": "string",
                        "enum": [
                            "single",
                            "sectioned"
                        ],
                        "example": "sectioned",
                        "description": "single: all section fields are cleared to null. sectioned: section fields you provide are saved. If general_prompt contains headings, they are split into empty section fields automatically."
                    },
                    "general_prompt": {
                        "type": "string",
                        "example": "You are a sales assistant...",
                        "description": "Main project instructions. May also be a full headed prompt; recognized headings are split into the matching section fields. Explicit section fields you send are kept."
                    },
                    "prompt_greetings": {
                        "type": "string",
                        "nullable": true,
                        "description": "Greeting phrases (only saved when prompt_mode = sectioned)"
                    },
                    "prompt_character": {
                        "type": "string",
                        "nullable": true,
                        "description": "Character / persona (only saved when prompt_mode = sectioned)"
                    },
                    "prompt_critical_instr": {
                        "type": "string",
                        "nullable": true,
                        "description": "Critical instructions (only saved when prompt_mode = sectioned)"
                    },
                    "prompt_transfer_instr": {
                        "type": "string",
                        "nullable": true,
                        "description": "Transfer instructions (only saved when prompt_mode = sectioned)"
                    },
                    "prompt_custom_vars": {
                        "type": "string",
                        "nullable": true,
                        "description": "Custom variables (only saved when prompt_mode = sectioned)"
                    },
                    "prompt_company_info": {
                        "type": "string",
                        "nullable": true,
                        "description": "Company info (only saved when prompt_mode = sectioned)"
                    },
                    "prompt_script_flow": {
                        "type": "string",
                        "nullable": true,
                        "description": "Script flow (only saved when prompt_mode = sectioned)"
                    },
                    "prompt_call_flow": {
                        "type": "string",
                        "nullable": true,
                        "description": "Call flow (only saved when prompt_mode = sectioned)"
                    },
                    "prompt_objections": {
                        "type": "string",
                        "nullable": true,
                        "description": "Common objections (only saved when prompt_mode = sectioned)"
                    },
                    "prompt_appt_flow": {
                        "type": "string",
                        "nullable": true,
                        "description": "Appointment flow (only saved when prompt_mode = sectioned)"
                    },
                    "prompt_faq_base": {
                        "type": "string",
                        "nullable": true,
                        "description": "FAQ / knowledge base (only saved when prompt_mode = sectioned)"
                    }
                }
            },
            "UpdateVoiceLanguageRequest": {
                "type": "object",
                "description": "Send only the fields you want to change. All fields are optional.",
                "properties": {
                    "model": {
                        "type": "string",
                        "example": "llama-3.3-70b-versatile",
                        "description": "AI model value from List AI Models (e.g. gpt-4.1-mini, llama-3.3-70b-versatile, deepseek-r1). Applied to agent config."
                    },
                    "voice_id": {
                        "type": "string",
                        "example": "zmcVlqmyk3Jpn5AVYcAL",
                        "description": "Voice ID from List Available Voices. Applied to agent config."
                    },
                    "language": {
                        "type": "string",
                        "example": "en-US",
                        "description": "Language value from List Languages (e.g. en-US). Applied to agent config."
                    },
                    "ambient_sound": {
                        "type": "string",
                        "nullable": true,
                        "example": "coffee-shop",
                        "description": "Background sound value from List Background Sounds. Send null to remove sound."
                    },
                    "ambient_sound_volume": {
                        "type": "number",
                        "format": "float",
                        "example": 0.6,
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Background sound volume (0.0 \u00e2\u20ac\u201c 1.0)"
                    },
                    "language_switching": {
                        "type": "boolean",
                        "example": true,
                        "description": "Enable/disable language switching."
                    },
                    "voice_speed": {
                        "type": "number",
                        "format": "float",
                        "example": 1.08,
                        "minimum": 0.7,
                        "maximum": 1.2,
                        "description": "Voice Speed slider (0.70 \u00e2\u20ac\u201c 1.20)"
                    },
                    "voice_stability": {
                        "type": "number",
                        "format": "float",
                        "example": 0.6,
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Stability slider (0.00 \u00e2\u20ac\u201c 1.00)"
                    },
                    "voice_similarity": {
                        "type": "number",
                        "format": "float",
                        "example": 0.8,
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Similarity Boost slider (0.00 \u00e2\u20ac\u201c 1.00)"
                    },
                    "voice_style": {
                        "type": "number",
                        "format": "float",
                        "example": 0.4,
                        "minimum": 0,
                        "maximum": 1,
                        "description": "Style slider (0.00 \u00e2\u20ac\u201c 1.00)"
                    },
                    "voice_temperature": {
                        "type": "number",
                        "format": "float",
                        "example": 0.95,
                        "minimum": 0,
                        "maximum": 2,
                        "description": "Temperature slider (0.00 \u00e2\u20ac\u201c 2.00)"
                    },
                    "volume": {
                        "type": "number",
                        "format": "float",
                        "example": 0.95,
                        "minimum": 0,
                        "maximum": 3,
                        "description": "Volume slider (0.00 \u00e2\u20ac\u201c 3.00)"
                    }
                }
            },
            "UpdateCallTimeLimitsRequest": {
                "type": "object",
                "description": "Send only the fields you want to change. Numeric values may be sent as JSON numbers (integers or floats); they are normalized before updating the agent config.",
                "properties": {
                    "end_call_after_silence_ms": {
                        "type": "integer",
                        "example": 10000,
                        "minimum": 10000,
                        "maximum": 1800000,
                        "description": "End call after this many ms of silence (10 000\u00e2\u20ac\u201c1 800 000 ms = 10 s\u00e2\u20ac\u201c30 min). Same as the End Call on Silence slider."
                    },
                    "max_call_duration_ms": {
                        "type": "integer",
                        "example": 900000,
                        "minimum": 60000,
                        "maximum": 7200000,
                        "description": "Maximum call length in ms (60 000\u00e2\u20ac\u201c7 200 000 ms = 1 min\u00e2\u20ac\u201c2 hr). Same as the Max Call Duration slider."
                    },
                    "begin_message_delay_ms": {
                        "type": "number",
                        "example": 0,
                        "minimum": 0,
                        "maximum": 5000,
                        "description": "Pause before the agent speaks, in ms (0\u00e2\u20ac\u201c5000). Integers are treated as ms. JSON floats between 0 and 5 (e.g. 0.5 or 2.0) are treated as seconds (same as the web slider), so 0.5 \u00e2\u2020\u2019 500 ms."
                    },
                    "publish": {
                        "type": "boolean",
                        "example": true,
                        "description": "Reserved for compatibility. Agent config updates are applied directly."
                    }
                }
            },
            "UpdateConversationSettingsRequest": {
                "type": "object",
                "description": "Send only the fields you want to change. Values 0.0\u00e2\u20ac\u201c1.0, same as the Conversation Settings sliders.",
                "properties": {
                    "responsiveness": {
                        "type": "number",
                        "format": "float",
                        "example": 0.5,
                        "minimum": 0,
                        "maximum": 1,
                        "description": "How fast the agent responds after the user stops speaking."
                    },
                    "interruption_sensitivity": {
                        "type": "number",
                        "format": "float",
                        "example": 0.8,
                        "minimum": 0,
                        "maximum": 1,
                        "description": "How easily the user can interrupt the agent."
                    }
                }
            },
            "AddPronunciationRequest": {
                "type": "object",
                "required": [
                    "word",
                    "alphabet"
                ],
                "description": "New pronunciation row \u00e2\u20ac\u201d same fields as the Pronunciation Setting modal on the manage page.",
                "properties": {
                    "word": {
                        "type": "string",
                        "example": "Rizzdial",
                        "description": "The word or phrase to pronounce."
                    },
                    "alphabet": {
                        "type": "string",
                        "enum": [
                            "ipa",
                            "cmu"
                        ],
                        "example": "ipa",
                        "description": "Phonetic alphabet \u00e2\u20ac\u201d \"ipa\" (International Phonetic Alphabet) or \"cmu\" (CMU Pronouncing Dictionary). Same as the Pronunciation dropdown on the manage page."
                    },
                    "phoneme": {
                        "type": "string",
                        "nullable": true,
                        "example": "\u00cb\u02c6r\u00c9\u00aazda\u00c9\u00aa\u00c9\u2122l",
                        "description": "Phoneme string (optional)."
                    }
                }
            },
            "UpdatePronunciationRequest": {
                "type": "object",
                "description": "Send only the fields you want to change.",
                "properties": {
                    "word": {
                        "type": "string",
                        "example": "Rizzdial",
                        "description": "Updated word or phrase."
                    },
                    "alphabet": {
                        "type": "string",
                        "enum": [
                            "ipa",
                            "cmu"
                        ],
                        "example": "ipa",
                        "description": "Phonetic alphabet \u00e2\u20ac\u201d \"ipa\" or \"cmu\"."
                    },
                    "phoneme": {
                        "type": "string",
                        "nullable": true,
                        "example": "\u00cb\u02c6r\u00c9\u00aazda\u00c9\u00aa\u00c9\u2122l",
                        "description": "Updated phoneme string."
                    }
                }
            },
            "UpdateEndCallFunctionRequest": {
                "type": "object",
                "required": [
                    "description"
                ],
                "properties": {
                    "description": {
                        "type": "string",
                        "example": "End the call when the user says goodbye.",
                        "description": "Instructions telling the AI agent when to trigger the End Call function. Same as the description field in the End Call modal on the Advanced tab."
                    }
                }
            },
            "UpdateApiConfigRequest": {
                "type": "object",
                "description": "CREATE: send function_name, api_url, api_method, api_content_type (required) + optional fields \u00e2\u20ac\u201d no config_id. UPDATE: send config_id + any fields to change. DELETE: send only delete_config_id.",
                "properties": {
                    "delete_config_id": {
                        "type": "integer",
                        "example": 12,
                        "description": "ID of the config to delete. When present, all other fields are ignored."
                    },
                    "config_id": {
                        "type": "integer",
                        "example": 12,
                        "description": "ID of the config to update. When present (and delete_config_id is absent), the entry is updated."
                    },
                    "function_name": {
                        "type": "string",
                        "example": "get_customer_info",
                        "description": "Unique function name for this API call (no spaces, use underscores)."
                    },
                    "function_prompt": {
                        "type": "string",
                        "nullable": true,
                        "example": "When the user asks for account info, call this function.",
                        "description": "Description telling the AI when to call this function. Auto-generated from api_body_template variables if omitted."
                    },
                    "api_url": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://api.example.com/customer",
                        "description": "Full URL of the external API endpoint."
                    },
                    "api_method": {
                        "type": "string",
                        "enum": [
                            "GET",
                            "POST",
                            "PUT",
                            "PATCH",
                            "DELETE"
                        ],
                        "example": "POST",
                        "description": "HTTP method for the API request."
                    },
                    "api_content_type": {
                        "type": "string",
                        "enum": [
                            "json",
                            "form"
                        ],
                        "example": "json",
                        "description": "\"json\" = application/json body; \"form\" = application/x-www-form-urlencoded."
                    },
                    "api_body_template": {
                        "type": "string",
                        "nullable": true,
                        "example": "phone={{phone}}&name={{name}}",
                        "description": "Query-string style template for the request body. Use {{variable}} placeholders \u00e2\u20ac\u201d the AI resolves these from the call context."
                    },
                    "api_timeout": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 120,
                        "example": 30,
                        "description": "Request timeout in seconds (1\u00e2\u20ac\u201c120)."
                    },
                    "api_headers": {
                        "type": "object",
                        "nullable": true,
                        "example": {
                            "Authorization": "Bearer token123"
                        },
                        "description": "Key-value map of HTTP headers to send with the request (e.g. Authorization, Content-Type)."
                    }
                }
            },
            "AddSenderRequest": {
                "type": "object",
                "required": [
                    "send_to",
                    "send_type"
                ],
                "properties": {
                    "send_to": {
                        "type": "string",
                        "example": "john@example.com",
                        "description": "Destination email address (for Email type) or phone number (for SMS type)"
                    },
                    "send_type": {
                        "type": "string",
                        "enum": [
                            "Email",
                            "SMS"
                        ],
                        "example": "Email",
                        "description": "Sender type: Email or SMS"
                    }
                }
            },
            "UpdateWebhookEndpointRequest": {
                "type": "object",
                "properties": {
                    "webhook_url": {
                        "type": "string",
                        "format": "uri",
                        "nullable": true,
                        "example": "https://example.com/webhook",
                        "description": "Full webhook URL. Send null or empty string to remove the webhook."
                    },
                    "webhook_method": {
                        "type": "string",
                        "enum": [
                            "GET",
                            "POST"
                        ],
                        "example": "POST",
                        "description": "HTTP method for the webhook request. Defaults to POST."
                    }
                }
            },
            "UpdateInboundGhlFieldsRequest": {
                "type": "object",
                "required": [
                    "mappings"
                ],
                "properties": {
                    "inbound_field_source": {
                        "type": "string",
                        "enum": [
                            "ghl",
                            "ai_sync"
                        ],
                        "example": "ghl",
                        "description": "Preferred source for mapped fields on an inbound call. ghl = GoHighLevel, ai_sync = AI Sync contact list. Omit to leave the current source unchanged."
                    },
                    "mappings": {
                        "type": "object",
                        "description": "Key-value pairs of local contact field name to GHL field key. Send `{}` to clear all mappings. Valid GHL keys: firstName, lastName, name, email, gender, phone, type, source, address1, city, state, postalCode, website, timezone.",
                        "additionalProperties": {
                            "type": "string"
                        },
                        "example": {
                            "first_name": "firstName",
                            "last_name": "lastName",
                            "email": "email"
                        }
                    }
                }
            },
            "UpdateWidgetConfigRequest": {
                "type": "object",
                "properties": {
                    "popup_position": {
                        "type": "string",
                        "nullable": true,
                        "example": "bottom-right",
                        "description": "Widget popup position (e.g. bottom-right, bottom-left)"
                    },
                    "background_color": {
                        "type": "string",
                        "nullable": true,
                        "example": "#ffffff",
                        "description": "Widget background color (hex)"
                    },
                    "text_color": {
                        "type": "string",
                        "nullable": true,
                        "example": "#000000",
                        "description": "Text color (hex)"
                    },
                    "button_color": {
                        "type": "string",
                        "nullable": true,
                        "example": "#4f46e5",
                        "description": "Primary button background color (hex)"
                    },
                    "button_text_color": {
                        "type": "string",
                        "nullable": true,
                        "example": "#ffffff",
                        "description": "Primary button text color (hex)"
                    },
                    "border_color": {
                        "type": "string",
                        "nullable": true,
                        "example": "#e5e7eb",
                        "description": "Widget border color (hex)"
                    },
                    "focus_outline_color": {
                        "type": "string",
                        "nullable": true,
                        "example": "#4f46e5",
                        "description": "Focus outline color for accessibility (hex)"
                    },
                    "card_radius": {
                        "type": "integer",
                        "nullable": true,
                        "example": 12,
                        "description": "Card border radius in pixels"
                    },
                    "button_radius": {
                        "type": "integer",
                        "nullable": true,
                        "example": 8,
                        "description": "Button border radius in pixels"
                    },
                    "start_call_text": {
                        "type": "string",
                        "nullable": true,
                        "example": "Start Call",
                        "description": "Label shown on the start call button"
                    },
                    "end_call_text": {
                        "type": "string",
                        "nullable": true,
                        "example": "End Call",
                        "description": "Label shown on the end call button"
                    },
                    "call_to_action_text": {
                        "type": "string",
                        "nullable": true,
                        "example": "Talk to AI",
                        "description": "Call-to-action text shown in the widget"
                    },
                    "speaking_status_text": {
                        "type": "string",
                        "nullable": true,
                        "example": "AI is speaking...",
                        "description": "Status text displayed while AI is speaking"
                    },
                    "avatar_image": {
                        "type": "string",
                        "nullable": true,
                        "example": null,
                        "description": "To upload a new avatar image send the request as multipart/form-data with the image file here (max 5 MB, supported: jpg, png, gif, webp). For JSON requests leave this field empty."
                    }
                }
            },
            "UpdateOutboundNumberRequest": {
                "type": "object",
                "required": [
                    "number_id"
                ],
                "properties": {
                    "number_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "MTI0",
                        "description": "Base64 encoded phone number ID (from Get Agent Phone Numbers or List AI Numbers). Send `null` to remove the current outbound assignment."
                    }
                }
            },
            "UpdateNumberPoolRequest": {
                "type": "object",
                "required": [
                    "number_ids"
                ],
                "properties": {
                    "direction": {
                        "type": "string",
                        "enum": [
                            "outbound",
                            "inbound",
                            "both"
                        ],
                        "description": "Outbound changes caller-ID rotation only. Inbound changes incoming-call routing only. Both edits complete pairs and preserves unrepresented partial or split assignments. Omission uses legacy pool scope, not explicit Both; retained directional assignments stay unchanged. Explicit writes require global directional activation."
                    },
                    "number_ids": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "MTIz",
                            "MTI0"
                        ],
                        "description": "Base64 encoded AI number IDs from Get Number Pool `available`. Send `[]` to clear only the selected direction. Saves are idempotent and preserve unchanged numbers and the other direction."
                    }
                }
            },
            "UnassignNumberPoolRequest": {
                "type": "object",
                "required": [
                    "number_id"
                ],
                "properties": {
                    "direction": {
                        "type": "string",
                        "enum": [
                            "outbound",
                            "inbound",
                            "both"
                        ],
                        "description": "Outbound changes caller-ID rotation only. Inbound changes incoming-call routing only. Both edits complete pairs and preserves unrepresented partial or split assignments. Omission uses legacy pool scope, not explicit Both; retained directional assignments stay unchanged. Explicit writes require global directional activation."
                    },
                    "number_id": {
                        "type": "string",
                        "example": "MTIz",
                        "description": "Base64 encoded AI number ID currently in this agent's pool."
                    }
                }
            },
            "UpdateInboundNumberRequest": {
                "type": "object",
                "required": [
                    "number_id"
                ],
                "properties": {
                    "number_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "MTIz",
                        "description": "Base64 encoded phone number ID (from Get Agent Phone Numbers or List AI Numbers). Send `null` to remove the current inbound assignment."
                    }
                }
            },
            "UpdatePressDigitRequest": {
                "type": "object",
                "required": [
                    "description"
                ],
                "properties": {
                    "description": {
                        "type": "string",
                        "maxLength": 1024,
                        "example": "You are calling a business that may have IVR. Listen carefully and press the right digit to reach the support department.",
                        "description": "Instructions telling the AI how to navigate the IVR menu. Same as the description field in the Press Digit modal on the Advanced tab. Max 1024 characters."
                    },
                    "delay_ms": {
                        "type": "integer",
                        "minimum": 100,
                        "maximum": 10000,
                        "example": 1000,
                        "description": "Pause detection delay in milliseconds before pressing a digit (100\u00e2\u20ac\u201c10000 ms). Defaults to 1000 ms if not provided."
                    }
                }
            },
            "UpdateJoinMeetingRequest": {
                "type": "object",
                "required": [
                    "description"
                ],
                "properties": {
                    "description": {
                        "type": "string",
                        "example": "When the user wants to join a meeting, use this function to connect them via Google Meet.",
                        "description": "Instructions telling the AI agent when to trigger the Join Meeting function. Same as the description field in the Join Meeting modal on the Advanced tab."
                    },
                    "google_calendar_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "cal_google_xyz789",
                        "description": "Google Calendar ID to connect the meeting. When provided, saved to the agent's google_calendar column."
                    }
                }
            },
            "UpdatePostCallRequest": {
                "type": "object",
                "description": "Updates post-call collection. `fields` is the GHL list. `aiSyncFields` is the AI Sync custom contact-column list. Omitted lists stay unchanged. Send an empty array to clear that list. Each entry must be \"column/Label\". Set isEnabled=false to disable both lists.",
                "properties": {
                    "isEnabled": {
                        "type": "boolean",
                        "example": true,
                        "description": "Set false to disable post-call collection and clear both GHL and AI Sync lists."
                    },
                    "fields": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "firstName/First Name",
                            "phone/Phone Number",
                            "email/Email Address"
                        ],
                        "description": "GHL field entries in \"field_id/Field Label\" format. Available default GHL field IDs: `firstName`, `lastName`, `name`, `email`, `gender`, `phone`, `type`, `source`, `address1`, `city`, `state`, `postalCode`, `website`, `timezone`. For GHL custom fields use: `CFRIZ_{field_id}_{field_name}/{field_label}`."
                    },
                    "aiSyncFields": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "ai_call_transcript/Call Transcript",
                            "ai_call_summary/Call Summary"
                        ],
                        "description": "AI Sync custom contact columns in \"column/Label\" format. Only custom contact columns are allowed (not default contact columns). Use GET /api/contacts/fields to list available columns. After the call, collected values are written onto the local contact."
                    }
                }
            },
            "UpdateLiveCallRequest": {
                "type": "object",
                "description": "Updates live-call field writes. `fields` is the GHL list. `aiSyncFields` is the AI Sync custom contact-column list. Omitted lists stay unchanged. Send an empty array to clear that list. Each entry must be \"column/Label\". Set isEnabled=false to disable both lists.",
                "properties": {
                    "isEnabled": {
                        "type": "boolean",
                        "example": true,
                        "description": "Set false to disable live-call updates and clear both GHL and AI Sync lists."
                    },
                    "fields": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "firstName/First Name",
                            "phone/Phone Number",
                            "email/Email Address"
                        ],
                        "description": "GHL field entries in \"field_id/Field Label\" format. The AI updates these CRM fields in real time during the call. Available default GHL field IDs: `firstName`, `lastName`, `name`, `email`, `gender`, `phone`, `type`, `source`, `address1`, `city`, `state`, `postalCode`, `website`, `timezone`. For GHL custom fields use: `CFRIZ_{field_id}_{field_name}/{field_label}`."
                    },
                    "aiSyncFields": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "ai_call_transcript/Call Transcript",
                            "preferred_time/Preferred Time"
                        ],
                        "description": "AI Sync custom contact columns in \"column/Label\" format. Only custom contact columns are allowed. Use GET /api/contacts/fields to list available columns. During the call, collected values are written onto the local contact."
                    }
                }
            },
            "UpdateCalendarFunctionRequest": {
                "type": "object",
                "description": "Send only the fields you want to change.",
                "properties": {
                    "book_appointments_on": {
                        "type": "string",
                        "enum": [
                            "GHL",
                            "Rizler"
                        ],
                        "example": "GHL",
                        "description": "\"GHL\" = use Go High Level calendar; \"Rizler\" = use Rizler platform calendar."
                    },
                    "calendar_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "cal_abc123",
                        "description": "GHL calendar ID. Used when book_appointments_on = \"GHL\"."
                    },
                    "calendar_name": {
                        "type": "string",
                        "nullable": true,
                        "example": "Sales Calendar",
                        "description": "GHL calendar display name."
                    },
                    "appointment_title": {
                        "type": "string",
                        "nullable": true,
                        "example": "Discovery Call",
                        "description": "Title shown on the calendar when an appointment is booked."
                    },
                    "upcoming_days": {
                        "type": "integer",
                        "minimum": 1,
                        "example": 7,
                        "description": "How many days ahead availability is checked when booking."
                    },
                    "timezone": {
                        "type": "string",
                        "nullable": true,
                        "example": "America/New_York",
                        "description": "Timezone of the calendar \u00e2\u20ac\u201d must match the timezone configured inside your GHL/Rizler calendar settings."
                    },
                    "user_info_fields": {
                        "type": "array",
                        "nullable": true,
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "first_name",
                            "email"
                        ],
                        "description": "Contact fields to collect from the caller during booking."
                    },
                    "rizler_calendar_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "rizler_cal_456",
                        "description": "Rizler calendar ID. Used when book_appointments_on = \"Rizler\"."
                    }
                }
            },
            "UpdateAppointmentCheckerRequest": {
                "type": "object",
                "required": [
                    "enabled"
                ],
                "description": "Turns the AI Appointment Checker on or off. When on, an outbound call is skipped if that lead matches the block choice: upcoming, past, or all appointments. A transferred lead is still skipped while the checker is on. Inbound calls and join-meeting calls are not blocked.",
                "properties": {
                    "enabled": {
                        "type": "boolean",
                        "example": true
                    },
                    "block": {
                        "type": "string",
                        "enum": [
                            "upcoming",
                            "past",
                            "all"
                        ],
                        "example": "upcoming",
                        "description": "Which appointments stop an outbound call. Omit to keep the saved choice."
                    }
                }
            },
            "UpdateCallTransferRequest": {
                "type": "object",
                "properties": {
                    "description": {
                        "type": "string",
                        "example": "Follow the transfer instructions to the letter.",
                        "description": "Instructions telling the AI agent when and how to trigger the Call Transfer function."
                    },
                    "displayed_number": {
                        "type": "string",
                        "example": "rizler",
                        "description": "\"rizler\" = display the agent's own number to the recipient. Any other value = the phone number string to display as caller ID."
                    },
                    "type_transfer": {
                        "type": "string",
                        "enum": [
                            "warm",
                            "cold"
                        ],
                        "example": "warm",
                        "description": "\"warm\" = agent stays on the line until a live human picks up then drops off gracefully. \"cold\" = agent drops immediately after dialing the transfer number."
                    },
                    "transfer_destination_type": {
                        "type": "string",
                        "enum": [
                            "static",
                            "dynamic"
                        ],
                        "example": "static",
                        "description": "\"static\" = always transfer to the same fixed phone number (transfer_number). \"dynamic\" = AI decides the destination based on call context (dynamicRoutingDescription)."
                    },
                    "transfer_number": {
                        "type": "string",
                        "nullable": true,
                        "example": "+14154155000",
                        "description": "E.164 phone number to transfer to. Required when transfer_destination_type = \"static\"."
                    },
                    "extension_number": {
                        "type": "boolean",
                        "example": false,
                        "description": "Whether to dial a DTMF extension after the call is connected. Set true and provide extension_value to use."
                    },
                    "extension_value": {
                        "type": "string",
                        "nullable": true,
                        "example": "101",
                        "description": "DTMF digits to press after connection (e.g. \"101\"). Used when extension_number = true."
                    },
                    "dynamic_routing_description": {
                        "type": "string",
                        "nullable": true,
                        "example": "Route to sales if user mentioned buying, else route to support.",
                        "description": "Instructions for the AI to determine the transfer destination dynamically. Used when transfer_destination_type = \"dynamic\"."
                    },
                    "on_hold_music": {
                        "type": "string",
                        "example": "none",
                        "description": "Hold music to play while connecting. \"none\" = silence. Other values depend on available audio options."
                    },
                    "navigate_ivr": {
                        "type": "boolean",
                        "example": false,
                        "description": "Whether the AI should navigate the destination's IVR menu automatically after transfer."
                    },
                    "navigate_ivr_description": {
                        "type": "string",
                        "nullable": true,
                        "example": "Press 1 for sales, then 2 for existing customers.",
                        "description": "Instructions for navigating the IVR. Used when navigate_ivr = true."
                    },
                    "human_detection": {
                        "type": "boolean",
                        "example": false,
                        "description": "Whether the AI should wait and confirm a live human answered before completing the warm transfer handoff."
                    },
                    "detection_timeout": {
                        "type": "integer",
                        "example": 30,
                        "description": "Seconds to wait for a human to answer before giving up. Used when human_detection = true."
                    },
                    "auto_greet": {
                        "type": "boolean",
                        "example": false,
                        "description": "Whether the AI should automatically greet the recipient once connected during a warm transfer."
                    },
                    "whisper_message": {
                        "type": "boolean",
                        "example": false,
                        "description": "Whether to play a whisper message to the recipient (transfer destination) before the caller is connected."
                    },
                    "whisper_handoff_message_type": {
                        "type": "string",
                        "enum": [
                            "prompt",
                            "static_message"
                        ],
                        "example": "prompt",
                        "description": "\"prompt\" = AI generates the whisper from the description. \"static_message\" = play the exact whisper_handoff_message_description text."
                    },
                    "whisper_handoff_message_description": {
                        "type": "string",
                        "nullable": true,
                        "example": "You are receiving a warm transfer from RizzDial AI.",
                        "description": "Whisper message content or prompt. Used when whisper_message = true."
                    },
                    "three_way_message": {
                        "type": "boolean",
                        "example": false,
                        "description": "Whether the AI should play a handoff message to all three parties (caller, recipient, agent) before dropping off."
                    },
                    "three_way_handoff_message_type": {
                        "type": "string",
                        "enum": [
                            "prompt",
                            "static_message"
                        ],
                        "example": "static_message",
                        "description": "\"prompt\" = AI generates the message. \"static_message\" = play the exact three_way_handoff_message_description text."
                    },
                    "three_way_handoff_message_description": {
                        "type": "string",
                        "nullable": true,
                        "example": "I'd like to introduce you to our sales specialist who will assist you further. Have a great day!",
                        "description": "Three-way handoff message content or prompt. Used when three_way_message = true."
                    }
                }
            },
            "UpdateBoostedKeywordsRequest": {
                "type": "object",
                "required": [
                    "boosted_keywords"
                ],
                "properties": {
                    "boosted_keywords": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "minItems": 1,
                        "example": [
                            "Rizzdial",
                            "CRM",
                            "AI agent"
                        ],
                        "description": "Full list of boosted keywords (replaces existing list). At least one keyword required."
                    }
                }
            },
            "UpdateGhlIntegrationRequest": {
                "type": "object",
                "description": "Same keys as GET /integration/{agent_id} response `data`. All fields optional \u00e2\u20ac\u201d include at least one; send `null` to clear a field.",
                "properties": {
                    "glocation_id": {
                        "type": "string",
                        "nullable": true,
                        "description": "GoHighLevel location ID.",
                        "example": "hbU9PklUNxdtFAVrehNb"
                    },
                    "send_recording_to_ghl": {
                        "type": "string",
                        "nullable": true,
                        "description": "GHL custom field ID (or mapping) for call recording URL.",
                        "example": "field_recording_001"
                    },
                    "send_transcription_to_ghl": {
                        "type": "string",
                        "nullable": true,
                        "description": "GHL field for full transcription.",
                        "example": "field_transcript_002"
                    },
                    "send_user_sentiment_to_ghl": {
                        "type": "string",
                        "nullable": true,
                        "description": "GHL field for sentiment.",
                        "example": "field_sentiment_003"
                    },
                    "send_call_summary_to_ghl": {
                        "type": "string",
                        "nullable": true,
                        "description": "GHL field for AI call summary.",
                        "example": "field_summary_004"
                    },
                    "send_call_duration_to_ghl_filed": {
                        "type": "string",
                        "nullable": true,
                        "description": "GHL field for call duration (name uses `filed` in API/DB).",
                        "example": "field_duration_005"
                    },
                    "send_agent_name_to_ghl_filed": {
                        "type": "string",
                        "nullable": true,
                        "description": "GHL field for agent name.",
                        "example": "field_agent_006"
                    },
                    "send_call_direction_to_ghl": {
                        "type": "string",
                        "nullable": true,
                        "description": "GHL field or label for inbound/outbound direction.",
                        "example": "Outbound"
                    },
                    "ghl_tag_on_answerd": {
                        "type": "string",
                        "nullable": true,
                        "description": "Tag applied when call is answered.",
                        "example": "answered"
                    },
                    "ghl_tag_on_no_answerd": {
                        "type": "string",
                        "nullable": true,
                        "description": "Tag when there is no answer.",
                        "example": "no-answer"
                    },
                    "ghl_tag_on_busy": {
                        "type": "string",
                        "nullable": true,
                        "description": "Tag when line is busy.",
                        "example": "busy"
                    },
                    "ghl_tag_on_inactivity": {
                        "type": "string",
                        "nullable": true,
                        "description": "Tag for inactivity timeout.",
                        "example": "inactivity"
                    },
                    "ghl_tag_on_appointment": {
                        "type": "string",
                        "nullable": true,
                        "description": "Tag when an appointment is booked.",
                        "example": "appointment-booked"
                    },
                    "ghl_tag_on_voicemail": {
                        "type": "string",
                        "nullable": true,
                        "description": "Tag for voicemail.",
                        "example": "voicemail"
                    },
                    "ghl_tag_user_hangup": {
                        "type": "string",
                        "nullable": true,
                        "description": "Tag when the user hangs up.",
                        "example": "user-hangup"
                    },
                    "ghl_tag_on_call_transfer": {
                        "type": "string",
                        "nullable": true,
                        "description": "Tag on warm/cold transfer.",
                        "example": "call-transfer"
                    },
                    "ghl_tag_on_failed_outbound_call": {
                        "type": "string",
                        "nullable": true,
                        "description": "Tag when outbound dial fails.",
                        "example": "failed-outbound"
                    }
                },
                "example": {
                    "glocation_id": "hbU9PklUNxdtFAVrehNb",
                    "send_recording_to_ghl": "field_recording_001",
                    "send_transcription_to_ghl": "field_transcript_002",
                    "send_user_sentiment_to_ghl": "field_sentiment_003",
                    "send_call_summary_to_ghl": "field_summary_004",
                    "send_call_duration_to_ghl_filed": "field_duration_005",
                    "send_agent_name_to_ghl_filed": "field_agent_006",
                    "send_call_direction_to_ghl": "Outbound",
                    "ghl_tag_on_answerd": "answered",
                    "ghl_tag_on_no_answerd": "no-answer",
                    "ghl_tag_on_busy": "busy",
                    "ghl_tag_on_inactivity": "inactivity",
                    "ghl_tag_on_appointment": "appointment-booked",
                    "ghl_tag_on_voicemail": "voicemail",
                    "ghl_tag_user_hangup": "user-hangup",
                    "ghl_tag_on_call_transfer": "call-transfer",
                    "ghl_tag_on_failed_outbound_call": "failed-outbound"
                }
            },
            "UpdateSmoothTalkRequest": {
                "type": "object",
                "required": [
                    "normalize_for_speech"
                ],
                "properties": {
                    "normalize_for_speech": {
                        "type": "boolean",
                        "example": true,
                        "description": "true to enable Smooth Talk, false to disable."
                    }
                }
            },
            "UpdateAutoRizzRequest": {
                "type": "object",
                "description": "Send only the fields you want to change.",
                "properties": {
                    "enable_backchannel": {
                        "type": "boolean",
                        "example": true,
                        "description": "Enable or disable the AutoRizz (backchannel) feature."
                    },
                    "backchannel_frequency": {
                        "type": "number",
                        "format": "float",
                        "minimum": 0,
                        "maximum": 1,
                        "example": 0.8,
                        "description": "How often the agent uses affirmations (0.0\u00e2\u20ac\u201c1.0)."
                    },
                    "backchannel_words": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "yeah",
                            "uh-huh",
                            "I see"
                        ],
                        "description": "List of words the agent uses for backchanneling. Must be non-empty when provided."
                    }
                }
            },
            "UpdateReminderSettingsRequest": {
                "type": "object",
                "description": "Send only the fields you want to change. Use reminder_trigger_sec (seconds) for convenience \u00e2\u20ac\u201d it is auto-converted to ms. Or send reminder_trigger_ms directly.",
                "properties": {
                    "reminder_trigger_sec": {
                        "type": "integer",
                        "minimum": 1,
                        "example": 10,
                        "description": "Reminder frequency in seconds (auto-converted to ms). Use this or reminder_trigger_ms."
                    },
                    "reminder_trigger_ms": {
                        "type": "integer",
                        "minimum": 1000,
                        "example": 10000,
                        "description": "Reminder frequency in milliseconds. Use this or reminder_trigger_sec."
                    },
                    "reminder_max_count": {
                        "type": "integer",
                        "minimum": 1,
                        "example": 3,
                        "description": "Maximum number of reminder messages to send."
                    }
                }
            },
            "AssignKnowledgeBaseRequest": {
                "type": "object",
                "required": [
                    "knowledge_base_ids"
                ],
                "description": "Full list of knowledge base IDs to attach to the agent config (replaces the previous selection). Send an empty array [] to clear all.",
                "properties": {
                    "knowledge_base_ids": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "knowledge_base_abc123",
                            "knowledge_base_xyz456"
                        ],
                        "description": "Knowledge base IDs (same as the Intelligence tab multi-select)."
                    }
                }
            },
            "UpdateRedialSettingsRequest": {
                "type": "object",
                "description": "Send only the fields you want to change. All values are saved to the local database.",
                "properties": {
                    "redial": {
                        "type": "integer",
                        "enum": [
                            0,
                            1
                        ],
                        "example": 1,
                        "description": "0 = disable redial, 1 = enable redial."
                    },
                    "redial_after": {
                        "type": "integer",
                        "enum": [
                            0,
                            1,
                            2,
                            3,
                            4,
                            5,
                            10,
                            15,
                            20,
                            25,
                            30,
                            45,
                            60
                        ],
                        "example": 5,
                        "description": "Minutes to wait before redialing. 0 = instantly. Allowed values: 0, 1, 2, 3, 4, 5, 10, 15, 20, 25, 30, 45, 60."
                    },
                    "redial_voicemail_detection": {
                        "type": "string",
                        "enum": [
                            "Yes",
                            "No"
                        ],
                        "example": "Yes",
                        "description": "\"Yes\" = redial even when a voicemail is detected. \"No\" = do not redial on voicemail."
                    },
                    "redial_agent_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "agent_abc123",
                        "description": "AI agent_id of a different agent to handle the redial call. Pass null to clear (use the same agent)."
                    }
                }
            },
            "UpdateVoicemailSettingsRequest": {
                "type": "object",
                "description": "Send only the fields you want to change. To disable voicemail detection send enable_voicemail_detection: false. To enable, set enable_voicemail_detection: true plus voicemail_action_type. To just change the action on an already-enabled agent, omit enable_voicemail_detection and send only voicemail_action_type (+ voicemail_message_text if needed).",
                "properties": {
                    "enable_voicemail_detection": {
                        "type": "boolean",
                        "example": true,
                        "description": "true = enable voicemail detection in agent config. false = disable. Omit to leave current enabled/disabled state unchanged."
                    },
                    "voicemail_action_type": {
                        "type": "string",
                        "enum": [
                            "hangup",
                            "static_text",
                            "prompt"
                        ],
                        "example": "static_text",
                        "description": "\"hangup\" \u00e2\u20ac\u201c hang up immediately when voicemail is detected. \"static_text\" \u00e2\u20ac\u201c play a fixed pre-written message. \"prompt\" \u00e2\u20ac\u201c generate a dynamic message using the LLM prompt. Required when enable_voicemail_detection is true (defaults to \"hangup\" if omitted). Also accepted standalone to update an existing action without re-toggling detection."
                    },
                    "voicemail_message_text": {
                        "type": "string",
                        "nullable": true,
                        "example": "Hi, you've reached our AI agent. Please leave a message and we'll get back to you shortly.",
                        "description": "The voicemail message text. Required when voicemail_action_type is \"static_text\" or \"prompt\". Ignored when voicemail_action_type is \"hangup\"."
                    },
                    "voicemail_detection_timeout_ms": {
                        "type": "integer",
                        "example": 30000,
                        "minimum": 5000,
                        "maximum": 120000,
                        "description": "How long the agent waits before deciding a call has reached voicemail, in milliseconds (5 000-120 000 ms = 5 s-2 min). Default is typically 30 000 ms (30 s)."
                    },
                    "voicemailHandling": {
                        "type": "string",
                        "enum": [
                            "hang_up",
                            "leave_message"
                        ],
                        "example": "hang_up",
                        "description": "V2 only. What to do when a machine answers. hang_up ends the call. leave_message plays staticPhrase / voicemail_message_text, or a generated message when behaviorType is smartV1."
                    },
                    "behaviorType": {
                        "type": "string",
                        "enum": [
                            "static",
                            "smartV1"
                        ],
                        "example": "static",
                        "description": "V2 only. static = fixed message. smartV1 = generated message."
                    },
                    "staticPhrase": {
                        "type": "string",
                        "nullable": true,
                        "example": "Please call us back.",
                        "description": "V2 only. Fixed message when leaving a voicemail."
                    },
                    "additionalInstructions": {
                        "type": "string",
                        "nullable": true,
                        "description": "V2 only. Instructions for a generated voicemail message."
                    },
                    "voiceRecognitionEnabled": {
                        "type": "boolean",
                        "example": true,
                        "description": "V2 only. Detect an answering machine by voice. Shown in the product as Advanced. Turning this on also enables voicemail detection."
                    },
                    "recognitionEngine": {
                        "type": "string",
                        "enum": [
                            "advanced"
                        ],
                        "example": "advanced",
                        "description": "V2 only. Voice recognition mode. The only accepted value is advanced."
                    },
                    "immediateDetection": {
                        "type": "boolean",
                        "example": false,
                        "description": "V2 only. true = decide faster with less confidence. false = listen a few seconds. Applies only while voice recognition is on."
                    }
                }
            },
            "ImportAgentRequest": {
                "type": "object",
                "description": "Two formats accepted: wrapped { \"agent_data\": { ...export data... } } or direct agent export data object. The payload must include agentExportData.",
                "properties": {
                    "agent_data": {
                        "type": "object",
                        "nullable": true,
                        "description": "FORMAT 1: Paste the full data object from Export AI Agent response here. If you use this key, all other fields are ignored."
                    },
                    "agentExportData": {
                        "type": "object",
                        "nullable": true,
                        "description": "FORMAT 2: Agent config (use when pasting export data directly without agent_data wrapper)"
                    },
                    "localAgentData": {
                        "type": "object",
                        "nullable": true,
                        "description": "FORMAT 2: Local metadata (status, GHL fields, etc.)"
                    },
                    "promptHistories": {
                        "type": "array",
                        "nullable": true,
                        "items": {
                            "type": "object"
                        },
                        "description": "FORMAT 2: Prompt history records"
                    },
                    "apiConfigurations": {
                        "type": "array",
                        "nullable": true,
                        "items": {
                            "type": "object"
                        },
                        "description": "FORMAT 2: API configuration records"
                    },
                    "senderRecords": {
                        "type": "array",
                        "nullable": true,
                        "items": {
                            "type": "object"
                        },
                        "description": "FORMAT 2: Sender records"
                    },
                    "widgetConfig": {
                        "type": "object",
                        "nullable": true,
                        "description": "FORMAT 2: Widget configuration"
                    }
                }
            },
            "CreateAgentFolderRequest": {
                "type": "object",
                "required": [
                    "f_name"
                ],
                "properties": {
                    "f_name": {
                        "type": "string",
                        "example": "Sales Agents",
                        "description": "Folder name (max 100 characters)",
                        "maxLength": 100
                    }
                }
            },
            "UpdateAgentFolderRequest": {
                "type": "object",
                "required": [
                    "f_name"
                ],
                "properties": {
                    "f_name": {
                        "type": "string",
                        "example": "Updated Folder Name",
                        "description": "New folder name (max 100 characters)",
                        "maxLength": 100
                    }
                }
            },
            "ReorderAgentFoldersRequest": {
                "type": "object",
                "required": [
                    "folder_ids"
                ],
                "properties": {
                    "folder_ids": {
                        "type": "array",
                        "description": "Ordered array of folder IDs (base64 encoded from List AI Agent Folders). Position 0 \u00e2\u2020\u2019 sort_order 1, position 1 \u00e2\u2020\u2019 sort_order 2, etc.",
                        "items": {
                            "type": "string",
                            "example": "MQ=="
                        },
                        "example": [
                            "Mw==",
                            "MQ==",
                            "NQ==",
                            "Mg=="
                        ]
                    }
                }
            },
            "PurchaseNumberRequest": {
                "type": "object",
                "required": [
                    "phone_token",
                    "provider",
                    "nickname"
                ],
                "properties": {
                    "phone_token": {
                        "type": "string",
                        "example": "KzE2MzA0MDg3OTY1L0NoaWNhZ28vSUwvNjMwL1VTL2xvY2Fs",
                        "description": "Base64 encoded phone token returned by GET /api/ai/number/search \u00e2\u20ac\u201d pass it exactly as received"
                    },
                    "provider": {
                        "type": "string",
                        "enum": [
                            "Twilio"
                        ],
                        "example": "Twilio",
                        "description": "Provider used to search (must match the search provider)"
                    },
                    "nickname": {
                        "type": "string",
                        "example": "Sales Line",
                        "description": "Display name for the number (required)"
                    },
                    "inbound_agent_id": {
                        "type": "string",
                        "example": "agent_abc123",
                        "nullable": true,
                        "description": "Agent ID to assign as inbound (optional)"
                    },
                    "outbound_agent_id": {
                        "type": "string",
                        "example": "agent_xyz456",
                        "nullable": true,
                        "description": "Agent ID to assign as outbound (optional)"
                    }
                }
            },
            "AssignNumberRequest": {
                "type": "object",
                "required": [
                    "number_id",
                    "agent_id",
                    "type"
                ],
                "properties": {
                    "number_id": {
                        "type": "string",
                        "example": "MTIz",
                        "description": "Base64 encoded number ID (from List AI Numbers API)"
                    },
                    "agent_id": {
                        "type": "string",
                        "example": "agent_abc123",
                        "description": "Agent ID (from List AI Agents API)"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "inbound",
                            "outbound"
                        ],
                        "example": "inbound",
                        "description": "Assignment type"
                    }
                }
            },
            "UnassignNumberRequest": {
                "type": "object",
                "required": [
                    "number_id",
                    "type"
                ],
                "properties": {
                    "number_id": {
                        "type": "string",
                        "example": "MTIz",
                        "description": "Base64 encoded number ID (from List AI Numbers API)"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "inbound",
                            "outbound"
                        ],
                        "example": "inbound",
                        "description": "Assignment type to remove"
                    }
                }
            },
            "UpdateNumberRequest": {
                "type": "object",
                "properties": {
                    "nickname": {
                        "type": "string",
                        "example": "Sales Line",
                        "nullable": true,
                        "description": "Display name for the number"
                    },
                    "inbound_agent_id": {
                        "type": "string",
                        "example": "agent_abc123",
                        "nullable": true,
                        "description": "Agent ID to assign as inbound (null to clear)"
                    },
                    "outbound_agent_id": {
                        "type": "string",
                        "example": "agent_xyz456",
                        "nullable": true,
                        "description": "Agent ID to assign as outbound (null to clear)"
                    }
                }
            },
            "MoveContactStageRequest": {
                "type": "object",
                "required": [
                    "contact_id",
                    "stage_id"
                ],
                "properties": {
                    "contact_id": {
                        "type": "string",
                        "example": "MQ==",
                        "description": "Base64 encoded contact ID (from List Pipeline Contacts API)"
                    },
                    "stage_id": {
                        "type": "string",
                        "example": "Mg==",
                        "description": "Base64 encoded target stage ID (from Get Pipeline Stages API)"
                    }
                }
            },
            "ReorderPipelineStagesRequest": {
                "type": "object",
                "required": [
                    "pipeline_id",
                    "stages"
                ],
                "properties": {
                    "pipeline_id": {
                        "type": "string",
                        "example": "MQ==",
                        "description": "Base64 encoded pipeline ID"
                    },
                    "stages": {
                        "type": "array",
                        "description": "Ordered list of stage IDs. The array position determines the final sorting_order \u00e2\u20ac\u201d first item becomes 0, second becomes 1, and so on. Any sorting_order field in each item is ignored; only the array order matters.",
                        "items": {
                            "type": "object",
                            "required": [
                                "id"
                            ],
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "example": "OTM=",
                                    "description": "Base64 encoded stage ID"
                                }
                            }
                        },
                        "example": [
                            {
                                "id": "OTM="
                            },
                            {
                                "id": "OTQ="
                            },
                            {
                                "id": "OTU="
                            }
                        ]
                    }
                }
            },
            "UpdatePipelineStageRequest": {
                "type": "object",
                "required": [
                    "stage_name"
                ],
                "properties": {
                    "stage_name": {
                        "type": "string",
                        "example": "Qualified",
                        "maxLength": 255,
                        "description": "New name for the stage."
                    }
                }
            },
            "AddPipelineStageRequest": {
                "type": "object",
                "required": [
                    "stage_name"
                ],
                "properties": {
                    "stage_name": {
                        "type": "string",
                        "example": "Qualified",
                        "maxLength": 255,
                        "description": "Name of the new stage to add"
                    }
                }
            },
            "CreatePipelineRequest": {
                "type": "object",
                "required": [
                    "name"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Sales Pipeline",
                        "maxLength": 255,
                        "description": "Pipeline name (required)"
                    },
                    "ghl_location_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "ve9EPM428h8vShlRW1KT",
                        "description": "Optional connected LeadConnector locationId. Omit or send empty to keep the board local (Don't sync). Must match GET /api/pipeline/ghl-locations or GET /api/settings/ghl/locations. The board and stages are created on that location when set."
                    },
                    "stages": {
                        "type": "array",
                        "nullable": true,
                        "description": "Optional list of stage names. Each item is a plain string. sorting_order is assigned automatically based on position in the array (first item = 0, second = 1, \u2026).",
                        "items": {
                            "type": "string",
                            "example": "New Lead"
                        },
                        "example": [
                            "New Lead",
                            "Positive",
                            "Negative"
                        ]
                    }
                }
            },
            "CreateDispositionRequest": {
                "type": "object",
                "required": [
                    "disposition"
                ],
                "properties": {
                    "disposition": {
                        "type": "string",
                        "maxLength": 150,
                        "example": "Appointment Set",
                        "description": "Disposition label (required, must be unique within your company)"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "Active",
                            "Inactive",
                            "Default"
                        ],
                        "example": "Active",
                        "description": "Row status. Default: Active (database default)."
                    },
                    "default_option": {
                        "type": "string",
                        "enum": [
                            "Active",
                            "Inactive",
                            "Default"
                        ],
                        "example": "Active",
                        "description": "Default-option flag used by the dialer UI. Default: Active."
                    },
                    "select_text_color": {
                        "type": "string",
                        "maxLength": 50,
                        "example": "#FFFFFF",
                        "description": "Text color when selected (hex). Default from database if omitted."
                    },
                    "select_bg_color": {
                        "type": "string",
                        "maxLength": 50,
                        "example": "#66FF00",
                        "description": "Background when selected (hex). Default from database if omitted."
                    },
                    "text_color": {
                        "type": "string",
                        "maxLength": 50,
                        "example": "#FFFFFF",
                        "description": "Label text color (hex). Default from database if omitted."
                    },
                    "bg_color": {
                        "type": "string",
                        "maxLength": 50,
                        "example": "#0000FF",
                        "description": "Label background color (hex). Default from database if omitted."
                    },
                    "call_status": {
                        "type": "string",
                        "enum": [
                            "No",
                            "Ringing",
                            "Answered",
                            "Busy",
                            "Canceled",
                            "No-answer",
                            "In-Progress",
                            "Failed",
                            "AMD",
                            "Completed"
                        ],
                        "example": "No",
                        "description": "Call outcome association. Default: No."
                    },
                    "ghl_accountid": {
                        "type": "string",
                        "maxLength": 50,
                        "nullable": true,
                        "description": "Optional GoHighLevel account id field."
                    },
                    "ghl_notecustid": {
                        "type": "string",
                        "maxLength": 50,
                        "nullable": true,
                        "description": "Optional GoHighLevel note customer id field."
                    },
                    "ghl_pipeline_id": {
                        "type": "string",
                        "maxLength": 100,
                        "nullable": true,
                        "description": "Optional exact HighLevel opportunity pipeline ID. Must be supplied with ghl_pipeline_stage_id and an owned ghl_accountid. Stored as unverified configuration until provider readback is available."
                    },
                    "ghl_pipeline_stage_id": {
                        "type": "string",
                        "maxLength": 100,
                        "nullable": true,
                        "description": "Optional exact HighLevel opportunity pipeline stage ID. Must be supplied with ghl_pipeline_id and an owned ghl_accountid. No provider opportunity mutation is attempted yet."
                    },
                    "role_view": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "MQ==",
                            "Mg=="
                        ],
                        "description": "Optional. Base64 encoded role IDs from GET /api/tags/contactTag/roles (same roles as contact tags). Only those roles will see this disposition in the dialer; omit or [] for no restriction."
                    }
                }
            },
            "PatchDispositionToggleRequest": {
                "type": "object",
                "description": "Optional body for disposition PATCH toggles. Omit entirely to flip from the current state.",
                "properties": {
                    "enabled": {
                        "type": "boolean",
                        "example": true,
                        "description": "Meaning depends on the endpoint: **PATCH \u00e2\u20ac\u00a6/status** = Didn't Answer (`status` Default vs Active). **PATCH \u00e2\u20ac\u00a6/default-option** = Setup Default Option (`default_option` Default vs Active). Only one disposition per company can be ON for each flag."
                    }
                }
            },
            "PatchDispositionCallStatusRequest": {
                "type": "object",
                "required": [
                    "call_status"
                ],
                "properties": {
                    "call_status": {
                        "type": "string",
                        "enum": [
                            "No",
                            "Ringing",
                            "Answered",
                            "Busy",
                            "Canceled",
                            "No-answer",
                            "In-Progress",
                            "Failed",
                            "AMD",
                            "Completed"
                        ],
                        "example": "Answered",
                        "description": "Allowed values: No, Ringing, Answered, Busy, Canceled, No-answer, In-Progress, Failed, AMD, Completed (Manage Dispositions Call Status / GET /api/disposition/meta/call-status-options)."
                    }
                }
            },
            "UpdateDispositionRolesRequest": {
                "type": "object",
                "required": [
                    "role_view"
                ],
                "properties": {
                    "role_view": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "MQ==",
                            "Mg=="
                        ],
                        "description": "Complete replacement list of base64 role IDs from GET /api/tags/contactTag/roles (same company roles as contact tags). Send [] to clear all role restrictions for this disposition."
                    }
                }
            },
            "BulkDeleteDispositionsRequest": {
                "type": "object",
                "required": [
                    "ids"
                ],
                "properties": {
                    "ids": {
                        "type": "array",
                        "minItems": 1,
                        "description": "Base64 encoded disposition IDs from List Dispositions (plain numeric strings are also accepted). Only rows belonging to the authenticated company are deleted.",
                        "items": {
                            "type": "string",
                            "example": "MQ=="
                        },
                        "example": [
                            "MQ==",
                            "Mg==",
                            "Mw=="
                        ]
                    }
                }
            },
            "UpdatePipelineRequest": {
                "type": "object",
                "required": [
                    "name"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Updated Pipeline Name",
                        "maxLength": 255,
                        "description": "New pipeline name."
                    },
                    "ghl_location_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "ve9EPM428h8vShlRW1KT",
                        "description": "Optional. Set only when the pipeline is not yet linked. Linked location cannot be changed."
                    }
                }
            },
            "GoogleAdsCreateCampaignRequest": {
                "type": "object",
                "required": [
                    "name"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255,
                        "example": "Search leads"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "PAUSED",
                            "ACTIVE"
                        ],
                        "example": "PAUSED",
                        "description": "Defaults to PAUSED. Spend does not start until ACTIVE/Resume."
                    },
                    "budget": {
                        "type": "number",
                        "example": 10,
                        "minimum": 1,
                        "description": "Daily budget in account currency. Default 10."
                    },
                    "channel": {
                        "type": "string",
                        "enum": [
                            "SEARCH",
                            "DISPLAY",
                            "DEMAND_GEN"
                        ],
                        "example": "SEARCH",
                        "description": "Defaults to SEARCH."
                    }
                }
            },
            "GoogleAdsUpdateCampaignRequest": {
                "type": "object",
                "required": [
                    "customer_id"
                ],
                "properties": {
                    "customer_id": {
                        "type": "string",
                        "example": "3514082235",
                        "description": "Google Ads customer id (digits only). Required."
                    },
                    "name": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "PAUSED",
                            "ACTIVE"
                        ]
                    }
                }
            },
            "GoogleAdsUpdateAdRequest": {
                "type": "object",
                "required": [
                    "customer_id",
                    "ad_group_id",
                    "status"
                ],
                "properties": {
                    "customer_id": {
                        "type": "string",
                        "example": "3514082235"
                    },
                    "ad_group_id": {
                        "type": "string",
                        "example": "123456789",
                        "description": "Digits from the ad_group resource (customers/\u2026/adGroups/{id})."
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "PAUSED",
                            "ACTIVE"
                        ]
                    }
                }
            },
            "GoogleAdsAssignPowerListRequest": {
                "type": "object",
                "properties": {
                    "power_list_id": {
                        "type": "integer",
                        "nullable": true,
                        "example": 1,
                        "description": "Company PowerList id. Null or empty uses Default."
                    }
                }
            },
            "GoogleAdsLeadFormMappingRequest": {
                "type": "object",
                "required": [
                    "mappings"
                ],
                "properties": {
                    "mappings": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string",
                            "nullable": true
                        },
                        "example": {
                            "FULL_NAME": "first_name",
                            "PHONE_NUMBER": "phone_number",
                            "EMAIL": "email"
                        },
                        "description": "Google question id \u2192 contact column. Empty/null skips that question."
                    }
                }
            },
            "MetaAdsCreateCampaignRequest": {
                "type": "object",
                "required": [
                    "name",
                    "objective"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255,
                        "example": "Spring leads"
                    },
                    "objective": {
                        "type": "string",
                        "enum": [
                            "OUTCOME_LEADS",
                            "OUTCOME_TRAFFIC",
                            "OUTCOME_ENGAGEMENT",
                            "OUTCOME_AWARENESS",
                            "OUTCOME_SALES",
                            "OUTCOME_APP_PROMOTION"
                        ],
                        "example": "OUTCOME_LEADS"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "PAUSED",
                            "ACTIVE"
                        ],
                        "example": "PAUSED",
                        "description": "Defaults to PAUSED."
                    }
                }
            },
            "MetaAdsUpdateRequest": {
                "type": "object",
                "description": "Send name and/or status. At least one is required.",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255,
                        "example": "Spring leads v2"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "PAUSED",
                            "ACTIVE"
                        ],
                        "example": "PAUSED"
                    }
                }
            },
            "MetaAdsCreateAdSetRequest": {
                "type": "object",
                "required": [
                    "name",
                    "optimization_goal",
                    "countries"
                ],
                "description": "Send daily_budget OR lifetime_budget (lifetime also needs end_time). Budgets are in whole currency units (converted to cents). LEAD_GENERATION also needs page_id. Created PAUSED unless status is ACTIVE.",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255,
                        "example": "US 25-55"
                    },
                    "daily_budget": {
                        "type": "number",
                        "minimum": 1,
                        "example": 20
                    },
                    "lifetime_budget": {
                        "type": "number",
                        "minimum": 1,
                        "example": 300
                    },
                    "start_time": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-10-10T09:00:00"
                    },
                    "end_time": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-10-31T23:59:00"
                    },
                    "optimization_goal": {
                        "type": "string",
                        "enum": [
                            "LEAD_GENERATION",
                            "LINK_CLICKS",
                            "LANDING_PAGE_VIEWS",
                            "REACH",
                            "IMPRESSIONS"
                        ],
                        "example": "LEAD_GENERATION"
                    },
                    "page_id": {
                        "type": "string",
                        "example": "5550001",
                        "description": "Required for LEAD_GENERATION. Must be a Page on the selected connection."
                    },
                    "countries": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 2
                        },
                        "example": [
                            "US"
                        ]
                    },
                    "age_min": {
                        "type": "integer",
                        "minimum": 13,
                        "maximum": 65,
                        "example": 25
                    },
                    "age_max": {
                        "type": "integer",
                        "minimum": 13,
                        "maximum": 65,
                        "example": 55
                    },
                    "genders": {
                        "type": "string",
                        "enum": [
                            "all",
                            "male",
                            "female"
                        ],
                        "example": "all"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "PAUSED",
                            "ACTIVE"
                        ],
                        "example": "PAUSED"
                    }
                }
            },
            "MetaAdsUpdateAdSetRequest": {
                "type": "object",
                "description": "Send only what changes. Targeting is replaced as a whole, so countries is required whenever any targeting field (countries, age_min, age_max, genders) is sent.",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "PAUSED",
                            "ACTIVE"
                        ]
                    },
                    "daily_budget": {
                        "type": "number",
                        "minimum": 1,
                        "example": 30
                    },
                    "lifetime_budget": {
                        "type": "number",
                        "minimum": 1
                    },
                    "start_time": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "end_time": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "countries": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "US",
                            "CA"
                        ]
                    },
                    "age_min": {
                        "type": "integer",
                        "minimum": 13,
                        "maximum": 65
                    },
                    "age_max": {
                        "type": "integer",
                        "minimum": 13,
                        "maximum": 65
                    },
                    "genders": {
                        "type": "string",
                        "enum": [
                            "all",
                            "male",
                            "female"
                        ]
                    }
                }
            },
            "MetaAdsDuplicateRequest": {
                "type": "object",
                "description": "Copies are always created PAUSED with \" - Copy\" added to the name. Ad sets are deep-copied (their ads come along).",
                "properties": {
                    "target_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "120200000000002",
                        "description": "Optional. For an ad set: the campaign to copy into. For an ad: the ad set to copy into. Must belong to this company."
                    }
                }
            },
            "MetaAdsCreateAdRequest": {
                "type": "object",
                "required": [
                    "name",
                    "adset_id",
                    "creative_id"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255,
                        "example": "Spring ad 1"
                    },
                    "adset_id": {
                        "type": "string",
                        "example": "120200000000002"
                    },
                    "creative_id": {
                        "type": "string",
                        "example": "120200000000003"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "PAUSED",
                            "ACTIVE"
                        ],
                        "example": "PAUSED"
                    }
                }
            },
            "MetaAdsCreateCreativeRequest": {
                "type": "object",
                "required": [
                    "name",
                    "page_id"
                ],
                "description": "Runs as one of the connection's Pages. Send image_hash OR video_id (video also needs thumbnail_hash). Send link, or lead_gen_form_id for an Instant Form creative (the link is then forced to https://fb.me/).",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255,
                        "example": "Spring creative"
                    },
                    "page_id": {
                        "type": "string",
                        "example": "5550001"
                    },
                    "message": {
                        "type": "string",
                        "maxLength": 2000,
                        "example": "Get a free quote today"
                    },
                    "headline": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "link": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://example.com/offer"
                    },
                    "call_to_action": {
                        "type": "string",
                        "enum": [
                            "LEARN_MORE",
                            "SIGN_UP",
                            "APPLY_NOW",
                            "CONTACT_US",
                            "GET_QUOTE",
                            "SUBSCRIBE",
                            "GET_OFFER",
                            "SHOP_NOW",
                            "BOOK_TRAVEL"
                        ],
                        "description": "Defaults to SIGN_UP with a Lead Form, otherwise LEARN_MORE."
                    },
                    "image_hash": {
                        "type": "string",
                        "example": "abc123hash",
                        "description": "From POST /media (type image)."
                    },
                    "video_id": {
                        "type": "string",
                        "example": "1234567890",
                        "description": "From POST /media (type video)."
                    },
                    "thumbnail_hash": {
                        "type": "string",
                        "description": "Required with video_id. Image hash used as the video thumbnail."
                    },
                    "lead_gen_form_id": {
                        "type": "string",
                        "example": "9990001",
                        "description": "An Instant Form that belongs to page_id."
                    }
                }
            },
            "MetaAdsMediaUploadRequest": {
                "type": "object",
                "required": [
                    "file"
                ],
                "properties": {
                    "file": {
                        "type": "string",
                        "format": "binary",
                        "description": "jpg, jpeg, png (max 8 MB) or mp4, mov (max 100 MB)."
                    }
                }
            },
            "MetaAdsCreateLeadFormRequest": {
                "type": "object",
                "required": [
                    "name",
                    "privacy_policy_url",
                    "follow_up_action_url",
                    "questions"
                ],
                "description": "Creates an Instant Form on the Page with standard contact questions. Needs the pages_manage_ads permission on the connection.",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255,
                        "example": "Spring Offer - Get a Quote"
                    },
                    "privacy_policy_url": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://example.com/privacy"
                    },
                    "privacy_policy_link_text": {
                        "type": "string",
                        "maxLength": 70,
                        "example": "Privacy Policy"
                    },
                    "follow_up_action_url": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://example.com/thank-you",
                        "description": "Required by Facebook. Opened after the lead submits."
                    },
                    "questions": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 12,
                        "items": {
                            "type": "string",
                            "enum": [
                                "FULL_NAME",
                                "FIRST_NAME",
                                "LAST_NAME",
                                "EMAIL",
                                "PHONE",
                                "CITY",
                                "STATE",
                                "ZIP",
                                "COUNTRY",
                                "COMPANY_NAME",
                                "JOB_TITLE"
                            ]
                        },
                        "example": [
                            "FULL_NAME",
                            "EMAIL",
                            "PHONE"
                        ]
                    }
                }
            },
            "MetaAdsAssignPowerListRequest": {
                "type": "object",
                "properties": {
                    "power_list_id": {
                        "type": "integer",
                        "nullable": true,
                        "example": 12,
                        "description": "Company PowerList id. Null or empty detaches the form from any PowerList."
                    }
                }
            },
            "MetaAdsLeadFormMappingRequest": {
                "type": "object",
                "required": [
                    "mappings"
                ],
                "properties": {
                    "mappings": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string",
                            "nullable": true
                        },
                        "example": {
                            "full_name": "first_name",
                            "phone_number": "phone_number",
                            "email": "email"
                        },
                        "description": "Facebook question key (field_key) \u2192 contact column. Null or empty clears that mapping."
                    }
                }
            },
            "MetaAdsConversionSettingsRequest": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 120,
                        "example": "Main Pixel",
                        "description": "Label shown in Meta Ads and in the workflow action picker."
                    },
                    "pixel_id": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 32,
                        "example": "123456789012345",
                        "description": "Meta Pixel / Dataset ID (digits only). Empty clears it."
                    },
                    "capi_access_token": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 512,
                        "example": "",
                        "description": "Conversions API token from Events Manager. Omit or leave empty to keep the existing token. Never returned after save."
                    }
                }
            },
            "MetaAdsConversionTestRequest": {
                "type": "object",
                "required": [
                    "test_event_code"
                ],
                "properties": {
                    "test_event_code": {
                        "type": "string",
                        "maxLength": 64,
                        "example": "TEST12345",
                        "description": "Required. Copy from Events Manager \u2192 Test events. Without this the event counts as a real conversion."
                    },
                    "event_name": {
                        "type": "string",
                        "maxLength": 50,
                        "example": "Lead",
                        "description": "Lead (default), Schedule, Purchase, or a CRM stage such as Qualified. Must start with a letter; letters, numbers, spaces, - or _ only."
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "lead@example.com"
                    },
                    "phone": {
                        "type": "string",
                        "example": "15551234567"
                    },
                    "value": {
                        "type": "number",
                        "minimum": 0,
                        "example": 1500,
                        "description": "Sale amount. Purchase always sends a value (defaults to 1 if omitted). Optional on other events."
                    },
                    "currency": {
                        "type": "string",
                        "minLength": 3,
                        "maxLength": 3,
                        "example": "USD",
                        "description": "3-letter currency, default USD. Used when value is sent."
                    }
                }
            },
            "LeadFormUpsertRequest": {
                "type": "object",
                "required": [
                    "name",
                    "powerlist_id"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 120,
                        "example": "Website form"
                    },
                    "powerlist_id": {
                        "type": "integer",
                        "example": 12,
                        "description": "Company PowerList id. Required. Contact is always attached to this list."
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "Active",
                            "Inactive"
                        ],
                        "example": "Active"
                    },
                    "fields": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string",
                            "enum": [
                                "required",
                                "optional",
                                "hidden"
                            ]
                        },
                        "example": {
                            "phone_number": "required",
                            "first_name": "required",
                            "last_name": "optional",
                            "email": "optional"
                        },
                        "description": "Contact column \u2192 required | optional | hidden. Phone is always required. Omit to use account defaults (phone + first name required, last name + email optional)."
                    },
                    "allowed_domains": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "example.com"
                        ],
                        "description": "Optional CORS allow-list for JS ingest. Empty means any Origin."
                    }
                }
            },
            "CarrierApplicationSubmitRequest": {
                "type": "object",
                "description": "multipart/form-data. Send legal_name, ein, entity, street, city, state, zip, or website when GET company left that field empty. The server copies a profile value only when it already matches what the carrier accepts. entity is Corporation, LLC, Partnership, Nonprofit, Sole Proprietor, or Other. signature_name must match signer_name exactly. consent_document is required when solicit or ai is yes. Each file is a PDF or image (png, jpg, jpeg, webp, heic, gif), 4 MB or smaller. Tick the agreements as 1.",
                "required": [
                    "main_phone",
                    "company_email",
                    "inc_state",
                    "year",
                    "signer_name",
                    "signer_title",
                    "signer_phone",
                    "signer_email",
                    "campaign",
                    "main_contact",
                    "main_contact_phone",
                    "billing_contact",
                    "billing_contact_phone",
                    "trace_name",
                    "trace_email",
                    "legal_on_calls",
                    "legal_action",
                    "solicit",
                    "ai",
                    "good_standing",
                    "agree",
                    "certify",
                    "signature_name",
                    "id_document",
                    "incorp_document"
                ],
                "properties": {
                    "legal_name": {
                        "type": "string",
                        "example": "Credit Optics Consulting LLC",
                        "description": "Send when GET company.legal_name is empty."
                    },
                    "ein": {
                        "type": "string",
                        "example": "12-3456789",
                        "description": "9 digits. Send when GET company.ein is empty."
                    },
                    "entity": {
                        "type": "string",
                        "enum": [
                            "Corporation",
                            "LLC",
                            "Partnership",
                            "Nonprofit",
                            "Sole Proprietor",
                            "Other"
                        ],
                        "example": "LLC",
                        "description": "Send when GET company.entity is empty. Limited Liability Corporation is not LLC."
                    },
                    "street": {
                        "type": "string",
                        "example": "2490 Lee Blvd",
                        "description": "Send when GET company.street is empty."
                    },
                    "city": {
                        "type": "string",
                        "example": "Cleveland Heights",
                        "description": "Send when GET company.city is empty."
                    },
                    "state": {
                        "type": "string",
                        "minLength": 2,
                        "maxLength": 2,
                        "example": "OH",
                        "description": "2 letters. Send when GET company.state is empty."
                    },
                    "zip": {
                        "type": "string",
                        "example": "44118",
                        "description": "Send when GET company.zip is empty."
                    },
                    "website": {
                        "type": "string",
                        "example": "https://creditopticsconsulting.com",
                        "description": "Optional. Send when GET company.website is empty."
                    },
                    "main_phone": {
                        "type": "string",
                        "example": "+15125550100"
                    },
                    "company_email": {
                        "type": "string",
                        "format": "email",
                        "example": "owner@example.com"
                    },
                    "inc_state": {
                        "type": "string",
                        "minLength": 2,
                        "maxLength": 2,
                        "example": "TX",
                        "description": "State of incorporation, 2 letters."
                    },
                    "year": {
                        "type": "string",
                        "example": "2018",
                        "description": "4 digits."
                    },
                    "signer_name": {
                        "type": "string",
                        "example": "Company Dev"
                    },
                    "signer_title": {
                        "type": "string",
                        "example": "Owner"
                    },
                    "signer_phone": {
                        "type": "string",
                        "example": "+15125550100"
                    },
                    "signer_email": {
                        "type": "string",
                        "format": "email",
                        "example": "owner@example.com"
                    },
                    "legal_on_calls": {
                        "type": "string",
                        "enum": [
                            "yes",
                            "no"
                        ],
                        "example": "yes"
                    },
                    "dba": {
                        "type": "string",
                        "description": "Required when legal_on_calls is no. The name spoken on calls."
                    },
                    "campaign": {
                        "type": "string",
                        "example": "Appointment reminders for existing customers"
                    },
                    "main_contact": {
                        "type": "string",
                        "example": "Company Dev"
                    },
                    "main_contact_phone": {
                        "type": "string",
                        "example": "+15125550100"
                    },
                    "billing_contact": {
                        "type": "string",
                        "example": "Company Dev"
                    },
                    "billing_contact_phone": {
                        "type": "string",
                        "example": "+15125550100"
                    },
                    "trace_name": {
                        "type": "string",
                        "example": "Company Dev",
                        "description": "Traceback contact. Must be able to answer within 24 hours."
                    },
                    "trace_email": {
                        "type": "string",
                        "format": "email",
                        "example": "owner@example.com"
                    },
                    "legal_action": {
                        "type": "string",
                        "enum": [
                            "yes",
                            "no"
                        ],
                        "example": "no"
                    },
                    "legal_detail": {
                        "type": "string",
                        "description": "Required when legal_action is yes."
                    },
                    "solicit": {
                        "type": "string",
                        "enum": [
                            "yes",
                            "no"
                        ],
                        "example": "no",
                        "description": "Telephone solicitations."
                    },
                    "dnc": {
                        "type": "string",
                        "enum": [
                            "yes",
                            "no"
                        ],
                        "description": "Required when solicit is yes."
                    },
                    "consent": {
                        "type": "string",
                        "enum": [
                            "yes",
                            "no"
                        ],
                        "description": "Required when solicit is yes."
                    },
                    "consent_how": {
                        "type": "string",
                        "description": "Required when solicit is yes and consent is yes."
                    },
                    "ai": {
                        "type": "string",
                        "enum": [
                            "yes",
                            "no"
                        ],
                        "example": "no",
                        "description": "AI or prerecorded voice."
                    },
                    "pewc": {
                        "type": "string",
                        "enum": [
                            "yes",
                            "no"
                        ],
                        "description": "Required when ai is yes."
                    },
                    "platform": {
                        "type": "string",
                        "example": "RizzDial",
                        "description": "When this is not empty, authorize_platform must be ticked."
                    },
                    "platform_contact": {
                        "type": "string",
                        "format": "email",
                        "description": "Optional platform contact email."
                    },
                    "authorize_platform": {
                        "type": "boolean",
                        "description": "Send 1 when ticked. Required when platform is not empty."
                    },
                    "good_standing": {
                        "type": "boolean",
                        "description": "Send 1."
                    },
                    "agree": {
                        "type": "boolean",
                        "description": "Send 1."
                    },
                    "certify": {
                        "type": "boolean",
                        "description": "Send 1."
                    },
                    "signature_name": {
                        "type": "string",
                        "example": "Company Dev",
                        "description": "Must match signer_name exactly."
                    },
                    "id_document": {
                        "type": "string",
                        "format": "binary",
                        "description": "Driver's license. PDF or image, 4 MB or smaller."
                    },
                    "incorp_document": {
                        "type": "string",
                        "format": "binary",
                        "description": "Proof of incorporation. PDF or image, 4 MB or smaller."
                    },
                    "consent_document": {
                        "type": "string",
                        "format": "binary",
                        "description": "Required when solicit or ai is yes. PDF or image, 4 MB or smaller."
                    }
                }
            },
            "CarrierApplicationFilesRequest": {
                "type": "object",
                "description": "multipart/form-data. Only when GET status is info_requested. Upload only the kinds listed in needs. Field names are file_id, file_incorp, file_consent, file_ein, and file_other. Same reference. PDF or image, 4 MB each.",
                "properties": {
                    "file_id": {
                        "type": "string",
                        "format": "binary",
                        "description": "Driver's license."
                    },
                    "file_incorp": {
                        "type": "string",
                        "format": "binary",
                        "description": "Proof of incorporation."
                    },
                    "file_consent": {
                        "type": "string",
                        "format": "binary",
                        "description": "Consent screenshots."
                    },
                    "file_ein": {
                        "type": "string",
                        "format": "binary",
                        "description": "IRS EIN letter."
                    },
                    "file_other": {
                        "type": "string",
                        "format": "binary",
                        "description": "Other document."
                    }
                }
            },
            "LeadFormIngestRequest": {
                "type": "object",
                "required": [
                    "phone_number"
                ],
                "properties": {
                    "phone_number": {
                        "type": "string",
                        "example": "2125550100"
                    },
                    "first_name": {
                        "type": "string",
                        "example": "Ali"
                    },
                    "last_name": {
                        "type": "string",
                        "example": "Khan"
                    },
                    "email": {
                        "type": "string",
                        "example": "ali@example.com"
                    }
                },
                "additionalProperties": true,
                "description": "Visible fields for that Lead Form. Phone upserts the Contact. Aliases: phone, phoneNumber, firstName, lastName."
            },
            "AddContactRequest": {
                "type": "object",
                "required": [
                    "phone_number",
                    "powerlist_id"
                ],
                "properties": {
                    "phone_number": {
                        "type": "string",
                        "example": "+16304087965"
                    },
                    "powerlist_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "first_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "last_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "email": {
                        "type": "string",
                        "nullable": true
                    }
                }
            },
            "AddContactNoteRequest": {
                "type": "object",
                "required": [
                    "contact_id",
                    "note"
                ],
                "properties": {
                    "contact_id": {
                        "type": "string",
                        "example": "MQ==",
                        "description": "Base64 encoded Contact ID (from List Contacts or Get Contact By ID API)"
                    },
                    "note": {
                        "type": "string",
                        "example": "Called and left a voicemail."
                    }
                }
            },
            "UpdateContactNoteRequest": {
                "type": "object",
                "required": [
                    "note"
                ],
                "properties": {
                    "note": {
                        "type": "string",
                        "example": "Updated note content."
                    }
                }
            },
            "CreatePowerlistRequest": {
                "type": "object",
                "required": [
                    "name"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Cold Leads",
                        "maxLength": 100,
                        "description": "Powerlist name (required, must be unique within your company)"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "Active",
                            "Inactive",
                            "Default"
                        ],
                        "example": "Active",
                        "description": "Powerlist status. Default: Active"
                    },
                    "priority": {
                        "type": "string",
                        "enum": [
                            "Highest",
                            "High",
                            "Medium",
                            "Low",
                            "Lowest"
                        ],
                        "example": "Medium",
                        "description": "Dialing priority level. Default: Medium"
                    },
                    "disposition_call": {
                        "type": "string",
                        "enum": [
                            "Yes",
                            "No"
                        ],
                        "example": "Yes",
                        "description": "Whether to prompt for disposition after each call. Default: Yes"
                    },
                    "call_timeout": {
                        "type": "string",
                        "enum": [
                            "15",
                            "20",
                            "25",
                            "30",
                            "35",
                            "40",
                            "45",
                            "50",
                            "55",
                            "60"
                        ],
                        "example": "25",
                        "description": "Seconds to wait before hanging up an unanswered call. Allowed: 15, 20, 25, 30, 35, 40, 45, 50, 55, 60. Default: 25"
                    },
                    "dial_at_a_time": {
                        "type": "integer",
                        "example": 1,
                        "minimum": 1,
                        "maximum": 5,
                        "description": "Number of simultaneous outbound calls. Range: 1 to 5"
                    },
                    "dail_max_daily": {
                        "type": "string",
                        "enum": [
                            "1",
                            "2",
                            "3",
                            "4",
                            "5",
                            "6",
                            "7",
                            "8",
                            "9",
                            "10"
                        ],
                        "example": "2",
                        "description": "Maximum dial attempts per contact per day. Allowed: 1\u00e2\u20ac\u201c10. Default: 2"
                    },
                    "dail_total_max": {
                        "type": "string",
                        "enum": [
                            "1",
                            "3",
                            "5",
                            "10",
                            "15",
                            "20",
                            "25",
                            "30",
                            "Infinite"
                        ],
                        "example": "3",
                        "description": "Maximum total dial attempts per contact across all days. Allowed: 1, 3, 5, 10, 15, 20, 25, 30, Infinite. Default: 3"
                    },
                    "max_contacts": {
                        "type": "integer",
                        "example": 100,
                        "minimum": 1,
                        "description": "Maximum number of contacts to dial in one session. Minimum: 1"
                    },
                    "next_powerlist_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "MQ==",
                        "description": "Base64 encoded ID of the powerlist to auto-start when this one finishes (from List Powerlists API). Send null or omit for none."
                    },
                    "ignore_dnc": {
                        "type": "string",
                        "enum": [
                            "Yes",
                            "No"
                        ],
                        "example": "No",
                        "description": "Legacy compatibility field. Calling Do Not Call opt-outs are always honored across PowerLists; this field cannot bypass them."
                    },
                    "dialed_reset_daily": {
                        "type": "string",
                        "enum": [
                            "No",
                            "Yes"
                        ],
                        "example": "No",
                        "description": "Whether to reset daily dial counts each day. Default: No"
                    },
                    "contact_redial": {
                        "type": "string",
                        "enum": [
                            "5 Minutes",
                            "10 Minutes",
                            "15 Minutes",
                            "30 Minutes",
                            "45 Minutes",
                            "1 Hour",
                            "2 Hours",
                            "3 Hours",
                            "5 Hours",
                            "12 Hours",
                            "1 Day",
                            "2 Days",
                            "3 Days",
                            "5 Days",
                            "1 Week"
                        ],
                        "example": "5 Minutes",
                        "description": "Wait time before redialing a contact. Allowed: 5 Minutes, 10 Minutes, 15 Minutes, 30 Minutes, 45 Minutes, 1 Hour, 2 Hours, 3 Hours, 5 Hours, 12 Hours, 1 Day, 2 Days, 3 Days, 5 Days, 1 Week. Default: 5 Minutes"
                    },
                    "start_time": {
                        "type": "string",
                        "example": "09:00",
                        "description": "Dialing window start time in HH:MM format (e.g. 09:00)"
                    },
                    "end_time": {
                        "type": "string",
                        "example": "17:00",
                        "description": "Dialing window end time in HH:MM format (e.g. 17:00)"
                    },
                    "ai_agent": {
                        "type": "string",
                        "nullable": true,
                        "example": "agent_14d79e07d01accbba8acd4e174",
                        "description": "AI agent_id string (from List AI Agents API \u00e2\u2020\u2019 agent_id field). Send null or omit to disable AI agent."
                    },
                    "ghl_tag": {
                        "type": "string",
                        "nullable": true,
                        "example": null,
                        "description": "GoHighLevel tag name to apply (max 100 chars). Optional."
                    },
                    "tags": {
                        "type": "array",
                        "nullable": true,
                        "description": "Array of base64 encoded Powerlist Tag IDs (from List Powerlist Tags API)",
                        "items": {
                            "type": "string",
                            "example": "MQ=="
                        },
                        "example": [
                            "MQ==",
                            "Mg=="
                        ]
                    },
                    "contact_fields": {
                        "type": "array",
                        "nullable": true,
                        "description": "Array of contact field names to display during the dialing session (e.g. first_name, last_name, phone_number, email)",
                        "items": {
                            "type": "string",
                            "example": "first_name"
                        },
                        "example": [
                            "first_name",
                            "last_name",
                            "phone_number"
                        ]
                    },
                    "members": {
                        "type": "array",
                        "nullable": true,
                        "description": "Array of plain integer user IDs to assign as powerlist members (use the numeric user ID, not base64)",
                        "items": {
                            "type": "integer",
                            "example": 3
                        },
                        "example": [
                            3,
                            5
                        ]
                    },
                    "dispositions": {
                        "type": "array",
                        "nullable": true,
                        "description": "Array of disposition links. Each item needs disposition_id (base64 encoded, from List Dispositions API) and trigger (when to apply: end_call, answered, no_answer, busy, failed, voicemail).",
                        "items": {
                            "type": "object",
                            "properties": {
                                "disposition_id": {
                                    "type": "string",
                                    "example": "MQ==",
                                    "description": "Base64 encoded Disposition ID (from List Dispositions API)"
                                },
                                "trigger": {
                                    "type": "string",
                                    "example": "end_call",
                                    "description": "When to apply this disposition: end_call, answered, no_answer, busy, failed, voicemail"
                                }
                            }
                        },
                        "example": [
                            {
                                "disposition_id": "MQ==",
                                "trigger": "end_call"
                            },
                            {
                                "disposition_id": "Mg==",
                                "trigger": "answered"
                            }
                        ]
                    }
                }
            },
            "PowerlistStatusRequest": {
                "type": "object",
                "required": [
                    "status"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": [
                            "Active",
                            "Inactive"
                        ],
                        "example": "Inactive",
                        "description": "New status for the powerlist"
                    }
                }
            },
            "CreatePowerlistNoteRequest": {
                "type": "object",
                "required": [
                    "title",
                    "notes",
                    "powerlist_id"
                ],
                "properties": {
                    "title": {
                        "type": "string",
                        "example": "Follow up needed",
                        "description": "Note title (required)"
                    },
                    "notes": {
                        "type": "string",
                        "example": "Call back on Monday to discuss pricing.",
                        "description": "Note content/body (required)"
                    },
                    "powerlist_id": {
                        "type": "array",
                        "description": "Array of base64 encoded Powerlist IDs. One note record is created per powerlist.",
                        "items": {
                            "type": "string",
                            "example": "MQ=="
                        },
                        "example": [
                            "MQ==",
                            "Mg=="
                        ]
                    }
                }
            },
            "UpdatePowerlistNoteRequest": {
                "type": "object",
                "properties": {
                    "title": {
                        "type": "string",
                        "example": "Follow up needed",
                        "description": "Note title (optional \u00e2\u20ac\u201d send only fields you want to update)"
                    },
                    "notes": {
                        "type": "string",
                        "example": "Call back on Tuesday instead.",
                        "description": "Note content/body (optional)"
                    },
                    "powerlist_id": {
                        "type": "string",
                        "example": "MQ==",
                        "description": "Base64 encoded Powerlist ID to reassign this note to (optional)"
                    }
                }
            },
            "ImportContactsRequest": {
                "type": "object",
                "required": [
                    "filepath",
                    "fields_mapping"
                ],
                "properties": {
                    "filepath": {
                        "type": "string",
                        "example": "uploads/tmp/1714000000file.csv",
                        "description": "Relative file path returned by the Upload Powerlist File API"
                    },
                    "fields_mapping": {
                        "type": "object",
                        "description": "Key-value mapping where each key is formField0, formField1, ... (one per file column in order) and the value is the contact field name to map to, or \"Ignore\" to skip that column. At least one column must be mapped to \"phone_number\".",
                        "example": {
                            "formField0": "first_name",
                            "formField1": "last_name",
                            "formField2": "phone_number",
                            "formField3": "Ignore"
                        },
                        "additionalProperties": {
                            "type": "string"
                        }
                    }
                }
            },
            "UploadPowerlistFileRequest": {
                "type": "object",
                "required": [
                    "file"
                ],
                "properties": {
                    "file": {
                        "type": "string",
                        "format": "binary",
                        "description": "CSV or Excel file to upload (allowed: csv, xlsx, xls)"
                    }
                }
            },
            "CreateVoiceTemplateRequest": {
                "type": "object",
                "required": [
                    "title",
                    "type"
                ],
                "properties": {
                    "title": {
                        "type": "string",
                        "maxLength": 255,
                        "example": "Intro Voicemail",
                        "description": "Template title (unique per company, same as the Voice Template manage screen)"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "text_to_speech",
                            "audio_file",
                            "record_voice"
                        ],
                        "example": "text_to_speech",
                        "description": "text_to_speech: use texttospeech body; audio_file or record_voice: upload MP3/WAV under audio"
                    },
                    "texttospeech": {
                        "type": "string",
                        "example": "Hi {{first_name}}, thanks for calling!",
                        "description": "Required when type is text_to_speech. Optional merge tokens as on the web screen."
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "inactive"
                        ],
                        "example": "active",
                        "description": "Defaults to active if omitted"
                    },
                    "audio": {
                        "type": "string",
                        "format": "binary",
                        "description": "Required when type is audio_file or record_voice. MP3 or WAV only (same rules as manage voice template upload)."
                    }
                }
            },
            "CreateVoiceCampaignRequest": {
                "type": "object",
                "required": [
                    "title",
                    "campaign_type"
                ],
                "properties": {
                    "title": {
                        "type": "string",
                        "maxLength": 50,
                        "example": "Cold Outreach",
                        "description": "Campaign title; must be unique within the company (same as the Voice Campaign manage screen)."
                    },
                    "campaign_type": {
                        "type": "string",
                        "enum": [
                            "ai",
                            "predictive"
                        ],
                        "example": "ai",
                        "description": "ai: AI dialing with optional AI agent and calls per hour; predictive: dialer assigns agents/voicemail template and All/Specific agent mode."
                    },
                    "powerlist_id": {
                        "type": "array",
                        "description": "Optional. One or more powerlist database IDs, or Base64 IDs as returned by List Powerlists. Must belong to the authenticated company. Omit or empty for none.",
                        "items": {
                            "type": "string",
                            "example": "MQ=="
                        }
                    },
                    "start_time": {
                        "type": "string",
                        "example": "09:00",
                        "description": "Optional. Dialing window start (HH:MM or HH:MM:SS)."
                    },
                    "end_time": {
                        "type": "string",
                        "example": "17:00",
                        "description": "Optional. Dialing window end."
                    },
                    "start_date": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-04-01",
                        "description": "Optional. Y-m-d"
                    },
                    "end_date": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-04-30",
                        "description": "Optional. Y-m-d"
                    },
                    "weekdays": {
                        "type": "array",
                        "description": "Optional. Days 0=Sunday through 6=Saturday (same as manage screen).",
                        "items": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 6
                        },
                        "example": [
                            1,
                            2,
                            3,
                            4,
                            5
                        ]
                    },
                    "delay_in_call": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10,
                        "example": 2,
                        "description": "Delay between calls in seconds (1\u00e2\u20ac\u201c10). Default 1."
                    },
                    "ai_agents": {
                        "type": "string",
                        "example": "5",
                        "description": "When campaign_type is ai: optional. Internal AI agent row ID (from AI Agents list) or Base64 of that id. Company-scoped. Omit or null for none."
                    },
                    "calls_per_hour": {
                        "type": "integer",
                        "example": 100,
                        "description": "When campaign_type is ai: optional cap on calls per hour."
                    },
                    "agent": {
                        "type": "string",
                        "enum": [
                            "All",
                            "Specific"
                        ],
                        "example": "All",
                        "description": "When campaign_type is predictive: All agents or Specific users. Defaults to All."
                    },
                    "specific_agents": {
                        "type": "array",
                        "description": "When campaign_type is predictive and agent is Specific: required non-empty list of user IDs (numeric or Base64) in this company with dialer access.",
                        "items": {
                            "type": "string",
                            "example": "MQ=="
                        }
                    },
                    "vm_id": {
                        "type": "string",
                        "example": "Mw==",
                        "description": "When campaign_type is predictive: optional voice template (voicemail) row ID for this company. Send **Base64** of the template id (same encoding as List Voice Templates / other manage APIs); plain numeric strings are also accepted."
                    }
                }
            },
            "UpdateVoiceCampaignRequest": {
                "type": "object",
                "required": [
                    "title",
                    "campaign_type"
                ],
                "properties": {
                    "title": {
                        "type": "string",
                        "maxLength": 50,
                        "example": "Cold Outreach Q2",
                        "description": "Campaign title; must be unique within the company (excluding current campaign)."
                    },
                    "campaign_type": {
                        "type": "string",
                        "enum": [
                            "ai",
                            "predictive"
                        ],
                        "example": "ai",
                        "description": "ai: AI dialing with optional AI agent and calls per hour; predictive: dialer assigns agents/voicemail template and All/Specific agent mode."
                    },
                    "powerlist_id": {
                        "type": "array",
                        "description": "Optional. One or more powerlist IDs (numeric or Base64 from List Powerlists). Replaces existing powerlist assignment. Must belong to the authenticated company.",
                        "items": {
                            "type": "string",
                            "example": "MQ=="
                        }
                    },
                    "start_time": {
                        "type": "string",
                        "example": "09:00",
                        "description": "Optional. Dialing window start (HH:MM or HH:MM:SS). Send null to clear."
                    },
                    "end_time": {
                        "type": "string",
                        "example": "17:00",
                        "description": "Optional. Dialing window end. Send null to clear."
                    },
                    "start_date": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-05-01",
                        "description": "Optional. Y-m-d. Send null to clear."
                    },
                    "end_date": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-05-31",
                        "description": "Optional. Y-m-d. Send null to clear."
                    },
                    "weekdays": {
                        "type": "array",
                        "description": "Optional. Days 0=Sunday through 6=Saturday.",
                        "items": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 6
                        },
                        "example": [
                            1,
                            2,
                            3,
                            4,
                            5
                        ]
                    },
                    "delay_in_call": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10,
                        "example": 2,
                        "description": "Delay between calls in seconds (1\u00e2\u20ac\u201c10). Default 1."
                    },
                    "ai_agents": {
                        "type": "string",
                        "example": "5",
                        "description": "When campaign_type is ai: optional AI agent row ID (numeric or Base64). Send null to clear."
                    },
                    "calls_per_hour": {
                        "type": "integer",
                        "example": 100,
                        "description": "When campaign_type is ai: optional cap on calls per hour."
                    },
                    "agent": {
                        "type": "string",
                        "enum": [
                            "All",
                            "Specific"
                        ],
                        "example": "All",
                        "description": "When campaign_type is predictive: All agents or Specific users."
                    },
                    "specific_agents": {
                        "type": "array",
                        "description": "When campaign_type is predictive and agent is Specific: required non-empty list of user IDs (numeric or Base64).",
                        "items": {
                            "type": "string",
                            "example": "MQ=="
                        }
                    },
                    "vm_id": {
                        "type": "string",
                        "example": "Mw==",
                        "description": "When campaign_type is predictive: optional voice template ID. **Base64** of the template id (same as List Voice Templates); plain numeric strings accepted. Send null to clear."
                    }
                }
            },
            "SpeedDialSaveRequest": {
                "type": "object",
                "required": [
                    "settings"
                ],
                "properties": {
                    "settings": {
                        "type": "array",
                        "minItems": 1,
                        "description": "Array of speed-dial rows to create or update. To update an existing row include its Base64 encoded id (from Get Speed Dial Settings). Omit id to create a new row.",
                        "items": {
                            "type": "object",
                            "required": [
                                "agent_count",
                                "cpa"
                            ],
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "nullable": true,
                                    "example": "MQ==",
                                    "description": "Base64 encoded speed-dial row ID (from Get Speed Dial Settings). Omit or null to create a new row."
                                },
                                "agent_count": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "example": 5,
                                    "description": "Number of agents threshold for this speed-dial tier."
                                },
                                "cpa": {
                                    "type": "number",
                                    "format": "float",
                                    "minimum": 0,
                                    "example": 8,
                                    "description": "Calls per agent for this tier."
                                }
                            }
                        }
                    }
                }
            },
            "UpdateVoiceTemplateRequest": {
                "type": "object",
                "required": [
                    "title",
                    "type"
                ],
                "properties": {
                    "title": {
                        "type": "string",
                        "maxLength": 255,
                        "example": "Intro Voicemail",
                        "description": "Template title (unique per company among other templates)"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "text_to_speech",
                            "audio_file",
                            "record_voice"
                        ],
                        "example": "text_to_speech",
                        "description": "text_to_speech: send texttospeech; audio types: send audio file to replace, or omit audio to keep the existing stored file"
                    },
                    "texttospeech": {
                        "type": "string",
                        "example": "Hi {{first_name}}, thanks for calling!",
                        "description": "Required when type is text_to_speech"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "inactive"
                        ],
                        "example": "active",
                        "description": "Omit to leave status unchanged"
                    },
                    "audio": {
                        "type": "string",
                        "format": "binary",
                        "description": "Optional. MP3 or WAV. When sent, replaces the stored audio and deletes the previous S3 object when applicable. Required when switching to audio_file/record_voice if the template has no audio yet."
                    }
                }
            },
            "UpdatePowerlistRequest": {
                "type": "object",
                "description": "All fields are optional. Only the fields you send will be updated. For members and dispositions, if the key is present the entire set is replaced (delete + re-insert).",
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Hot Leads",
                        "maxLength": 100,
                        "description": "New powerlist name (must be unique within company)"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "Active",
                            "Inactive",
                            "Default"
                        ],
                        "example": "Active",
                        "description": "Powerlist status"
                    },
                    "priority": {
                        "type": "string",
                        "enum": [
                            "Highest",
                            "High",
                            "Medium",
                            "Low",
                            "Lowest"
                        ],
                        "example": "High",
                        "description": "Dialing priority level"
                    },
                    "disposition_call": {
                        "type": "string",
                        "enum": [
                            "Yes",
                            "No"
                        ],
                        "example": "Yes",
                        "description": "Whether to prompt for disposition after each call"
                    },
                    "call_timeout": {
                        "type": "string",
                        "enum": [
                            "15",
                            "20",
                            "25",
                            "30",
                            "35",
                            "40",
                            "45",
                            "50",
                            "55",
                            "60"
                        ],
                        "example": "30",
                        "description": "Seconds before hanging up unanswered call. Allowed: 15, 20, 25, 30, 35, 40, 45, 50, 55, 60"
                    },
                    "dial_at_a_time": {
                        "type": "integer",
                        "example": 2,
                        "minimum": 1,
                        "maximum": 5,
                        "description": "Number of simultaneous outbound calls. Range: 1 to 5"
                    },
                    "dail_max_daily": {
                        "type": "string",
                        "enum": [
                            "1",
                            "2",
                            "3",
                            "4",
                            "5",
                            "6",
                            "7",
                            "8",
                            "9",
                            "10"
                        ],
                        "example": "3",
                        "description": "Max dial attempts per contact per day. Allowed: 1\u00e2\u20ac\u201c10"
                    },
                    "dail_total_max": {
                        "type": "string",
                        "enum": [
                            "1",
                            "3",
                            "5",
                            "10",
                            "15",
                            "20",
                            "25",
                            "30",
                            "Infinite"
                        ],
                        "example": "5",
                        "description": "Max total dial attempts per contact. Allowed: 1, 3, 5, 10, 15, 20, 25, 30, Infinite"
                    },
                    "max_contacts": {
                        "type": "integer",
                        "example": 200,
                        "minimum": 1,
                        "description": "Maximum contacts to dial per session. Minimum: 1"
                    },
                    "next_powerlist_id": {
                        "type": "string",
                        "nullable": true,
                        "example": "MQ==",
                        "description": "Base64 encoded ID of the powerlist to auto-start when this one finishes (from List Powerlists API). Send null or omit for none."
                    },
                    "ignore_dnc": {
                        "type": "string",
                        "enum": [
                            "Yes",
                            "No"
                        ],
                        "example": "No",
                        "description": "Legacy compatibility field. Calling Do Not Call opt-outs are always honored across PowerLists; this field cannot bypass them."
                    },
                    "dialed_reset_daily": {
                        "type": "string",
                        "enum": [
                            "No",
                            "Yes"
                        ],
                        "example": "Yes",
                        "description": "Whether to reset daily dial counts each day"
                    },
                    "contact_redial": {
                        "type": "string",
                        "enum": [
                            "5 Minutes",
                            "10 Minutes",
                            "15 Minutes",
                            "30 Minutes",
                            "45 Minutes",
                            "1 Hour",
                            "2 Hours",
                            "3 Hours",
                            "5 Hours",
                            "12 Hours",
                            "1 Day",
                            "2 Days",
                            "3 Days",
                            "5 Days",
                            "1 Week"
                        ],
                        "example": "10 Minutes",
                        "description": "Wait time before redialing a contact. Allowed: 5 Minutes, 10 Minutes, 15 Minutes, 30 Minutes, 45 Minutes, 1 Hour, 2 Hours, 3 Hours, 5 Hours, 12 Hours, 1 Day, 2 Days, 3 Days, 5 Days, 1 Week"
                    },
                    "start_time": {
                        "type": "string",
                        "example": "09:00",
                        "description": "Dialing window start time in HH:MM format"
                    },
                    "end_time": {
                        "type": "string",
                        "example": "17:00",
                        "description": "Dialing window end time in HH:MM format"
                    },
                    "ai_agent": {
                        "type": "string",
                        "nullable": true,
                        "example": "agent_14d79e07d01accbba8acd4e174",
                        "description": "AI agent_id string (from List AI Agents API \u00e2\u2020\u2019 agent_id field). Send null to disable AI agent."
                    },
                    "ghl_tag": {
                        "type": "string",
                        "nullable": true,
                        "example": null,
                        "description": "GoHighLevel tag name (max 100 chars). Send null to clear."
                    },
                    "tags": {
                        "type": "array",
                        "nullable": true,
                        "description": "Array of base64 encoded Powerlist Tag IDs. If present, replaces existing tags.",
                        "items": {
                            "type": "string",
                            "example": "MQ=="
                        },
                        "example": [
                            "MQ==",
                            "Mg=="
                        ]
                    },
                    "contact_fields": {
                        "type": "array",
                        "nullable": true,
                        "description": "Array of contact field names. If present, replaces existing contact fields.",
                        "items": {
                            "type": "string",
                            "example": "first_name"
                        },
                        "example": [
                            "first_name",
                            "last_name",
                            "email_Address"
                        ]
                    },
                    "members": {
                        "type": "array",
                        "nullable": true,
                        "description": "Array of plain integer user IDs. If present, replaces all existing members.",
                        "items": {
                            "type": "integer",
                            "example": 3
                        },
                        "example": [
                            3,
                            5
                        ]
                    },
                    "dispositions": {
                        "type": "array",
                        "nullable": true,
                        "description": "Array of disposition links. If present, replaces all existing dispositions. disposition_id is base64 encoded (from List Dispositions API). Trigger options: end_call, answered, no_answer, busy, failed, voicemail.",
                        "items": {
                            "type": "object",
                            "properties": {
                                "disposition_id": {
                                    "type": "string",
                                    "example": "MQ==",
                                    "description": "Base64 encoded Disposition ID"
                                },
                                "trigger": {
                                    "type": "string",
                                    "example": "end_call",
                                    "description": "When to apply: end_call, answered, no_answer, busy, failed, voicemail"
                                }
                            }
                        },
                        "example": [
                            {
                                "disposition_id": "MQ==",
                                "trigger": "end_call"
                            }
                        ]
                    }
                }
            },
            "CreateWorkflowRequest": {
                "type": "object",
                "required": [
                    "name"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "My Workflow",
                        "maxLength": 255
                    },
                    "description": {
                        "type": "string",
                        "nullable": true,
                        "example": "Workflow description"
                    },
                    "trigger_config": {
                        "type": "array",
                        "nullable": true,
                        "description": "Optional trigger configuration (same shape as the web workflow form).",
                        "items": {
                            "type": "object"
                        }
                    }
                }
            },
            "UpdateWorkflowRequest": {
                "type": "object",
                "required": [
                    "name",
                    "status"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "My Workflow",
                        "maxLength": 255
                    },
                    "description": {
                        "type": "string",
                        "nullable": true,
                        "example": "Workflow description"
                    },
                    "trigger_config": {
                        "type": "array",
                        "nullable": true,
                        "description": "Trigger configuration (same as web workflow update).",
                        "items": {
                            "type": "object"
                        }
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "inactive",
                            "draft"
                        ],
                        "example": "active"
                    }
                }
            },
            "WorkflowStatusUpdateRequest": {
                "type": "object",
                "required": [
                    "status"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "active"
                    }
                }
            },
            "CreateWorkflowFolderRequest": {
                "type": "object",
                "required": [
                    "f_name"
                ],
                "properties": {
                    "f_name": {
                        "type": "string",
                        "example": "My Folder",
                        "maxLength": 100
                    }
                }
            },
            "ReorderWorkflowFoldersRequest": {
                "type": "object",
                "required": [
                    "folder_ids"
                ],
                "properties": {
                    "folder_ids": {
                        "type": "array",
                        "description": "Workflow folder IDs in the desired display order (first index = top). Use base64 ids from List Workflow Folders, or numeric database ids.",
                        "minItems": 1,
                        "items": {
                            "oneOf": [
                                {
                                    "type": "string",
                                    "example": "MQ==",
                                    "description": "Base64-encoded folder id"
                                },
                                {
                                    "type": "integer",
                                    "example": 1,
                                    "description": "Numeric folder id"
                                }
                            ]
                        },
                        "example": [
                            "MQ==",
                            "Mg==",
                            "Mw=="
                        ]
                    }
                }
            },
            "MoveWorkflowToFolderRequest": {
                "type": "object",
                "required": [
                    "folder_id"
                ],
                "properties": {
                    "folder_id": {
                        "type": "string",
                        "description": "Base64-encoded folder id from List Workflow Folders (same as each record's id). Use MA== for uncategorized (no folder). Numeric ids are not accepted.",
                        "example": "MQ=="
                    }
                }
            },
            "SaveWorkflowBuilderGraphRequest": {
                "type": "object",
                "required": [
                    "trigger_config"
                ],
                "description": "Only one root field: trigger_config. Each triggers[].type and actions[].type must match GET /api/Workflow/catalog/triggers and /actions (or GET /api/Workflow/builder/{id}). Live types include appointment_status, openai_gpt, send_meta_conversion and add_to_powerlist. Do not use legacy names like new_contact.",
                "properties": {
                    "trigger_config": {
                        "type": "object",
                        "description": "Full graph. Same shape as GET builder data.trigger_config. Newer filters: appointment_status (event_type, booking_status including no_show, actor_type, tags has, calendar_id); contact_changed (tags added/removed, custom_field, changed_fields); If/Else GPT / Claude field gpt:<openai_gpt node id> or gpt. openai_gpt config: { prompt, provider?: openai|claude, model?, action_type? }. send_meta_conversion config: { conversion_id, event_name: Lead|Schedule|Purchase|Custom, custom_event_name?, value?, currency? }. Purchase needs value (number or {{contact.deal_value}}). conversion_id comes from GET /api/Workflow/builder/helpers/meta-conversions or GET /api/marketing/meta-ads/conversions.",
                        "additionalProperties": true
                    }
                },
                "example": {
                    "trigger_config": {
                        "triggers": [
                            {
                                "id": "trigger-node-1",
                                "type": "appointment_status",
                                "name": "Appointment Status",
                                "description": "Triggers when a Rizz Calendar booking is created or its status changes",
                                "filters": [
                                    {
                                        "field": "booking_status",
                                        "operator": "equals",
                                        "value": "no_show"
                                    }
                                ]
                            }
                        ],
                        "actions": [
                            {
                                "id": "action-gpt-1",
                                "type": "openai_gpt",
                                "name": "GPT / Claude",
                                "config": {
                                    "prompt": "Summarize {{contact.first_name}} in one sentence.",
                                    "model": "gpt-4o-mini",
                                    "action_type": "custom"
                                }
                            }
                        ],
                        "nodes": [
                            {
                                "id": "node-trigger-1",
                                "type": "trigger",
                                "position": {
                                    "x": 120,
                                    "y": 80
                                },
                                "data": {
                                    "label": "Appointment Status",
                                    "triggerId": "trigger-node-1"
                                }
                            },
                            {
                                "id": "node-action-1",
                                "type": "action",
                                "position": {
                                    "x": 120,
                                    "y": 220
                                },
                                "data": {
                                    "label": "GPT / Claude",
                                    "actionId": "action-gpt-1"
                                }
                            }
                        ],
                        "edges": [
                            {
                                "id": "edge-1",
                                "source": "node-trigger-1",
                                "target": "node-action-1",
                                "sourceHandle": null,
                                "targetHandle": null
                            }
                        ]
                    }
                }
            },
            "WorkflowSettingsUpdateRequest": {
                "type": "object",
                "required": [
                    "timezone_id"
                ],
                "description": "Same fields as the workflow builder \u00e2\u20ac\u0153Save settings\u00e2\u20ac\u009d (web). time_window_enabled defaults to false when omitted.",
                "properties": {
                    "timezone_id": {
                        "type": "string",
                        "description": "Base64-encoded timezone ID. Encode the numeric id from the timezones list returned by GET /api/Workflow/builder/{id}. Example: timezone id 40 \u2192 base64_encode(\"40\") = \"NDA=\".",
                        "example": "NDA="
                    },
                    "time_window_enabled": {
                        "type": "boolean",
                        "example": true
                    },
                    "start_time": {
                        "type": "string",
                        "example": "09:00",
                        "description": "H:i when time_window_enabled is true"
                    },
                    "end_time": {
                        "type": "string",
                        "example": "17:00",
                        "description": "H:i when time_window_enabled is true"
                    },
                    "include_days": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "mon",
                            "tue",
                            "wed",
                            "thu",
                            "fri"
                        ]
                    },
                    "from_name": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "from_email": {
                        "type": "string",
                        "format": "email",
                        "nullable": true
                    },
                    "from_number": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "allowed_users": {
                        "type": "array",
                        "nullable": true,
                        "items": {
                            "type": "integer"
                        },
                        "description": "User ids allowed to run this workflow (Company accounts)."
                    }
                }
            },
            "WorkflowEnrollContactRequest": {
                "type": "object",
                "required": [
                    "contact_id"
                ],
                "description": "Manually enroll a contact into an active workflow. A new execution record is created each time (re-enrollment is allowed).",
                "properties": {
                    "contact_id": {
                        "type": "string",
                        "description": "Base64-encoded contact ID. Encode the numeric contact id \u2014 e.g. contact id 101 \u2192 base64_encode(\"101\") = \"MTAx\".",
                        "example": "MTAx"
                    }
                }
            },
            "WorkflowBuilderTestRequest": {
                "type": "object",
                "description": "Fire a test run. Works on draft workflows. Provide contact_id or phone. trigger_type can be any live catalog type including appointment_status.",
                "properties": {
                    "contact_id": {
                        "type": "integer",
                        "example": 101
                    },
                    "phone": {
                        "type": "string",
                        "example": "+15551234567"
                    },
                    "first_name": {
                        "type": "string"
                    },
                    "last_name": {
                        "type": "string"
                    },
                    "email": {
                        "type": "string"
                    },
                    "trigger_id": {
                        "type": "string",
                        "description": "Trigger node id from the graph"
                    },
                    "trigger_type": {
                        "type": "string",
                        "example": "appointment_status",
                        "description": "Catalog type, e.g. appointment_status, contact_changed, contact_created"
                    },
                    "call_status": {
                        "type": "string"
                    },
                    "test_reply": {
                        "type": "string",
                        "example": "now works",
                        "description": "Test runs never wait. A \"Wait for reply\" step takes its Replied path with this text ({{reply.text}}, If/Else last_reply). Omit it for the No reply path. Also accepted inside trigger_data."
                    },
                    "test_business_hours": {
                        "type": "string",
                        "enum": [
                            "open",
                            "closed"
                        ],
                        "description": "Force the If/Else business_hours condition in this test run. Omit it to use the real hours right now. Also accepted inside trigger_data."
                    }
                }
            },
            "OpenAiSettingsUpdateRequest": {
                "type": "object",
                "description": "Company OpenAI key used by the GPT / Claude (openai_gpt) workflow action. API key is never returned. enabled=true requires a key.",
                "properties": {
                    "enabled": {
                        "type": "boolean",
                        "example": true
                    },
                    "api_key": {
                        "type": "string",
                        "description": "Omit to keep the stored key."
                    }
                }
            },
            "ContactWorkflowScheduleRequest": {
                "type": "object",
                "required": [
                    "workflow_id",
                    "date",
                    "time"
                ],
                "description": "Schedule a workflow to enroll this contact at a local date/time (user profile timezone, stored UTC).",
                "properties": {
                    "workflow_id": {
                        "type": "integer",
                        "example": 2
                    },
                    "date": {
                        "type": "string",
                        "example": "2026-09-20",
                        "description": "Y-m-d"
                    },
                    "time": {
                        "type": "string",
                        "example": "09:30",
                        "description": "H:i"
                    }
                }
            }
        }
    },
    "tags": [
        {
            "name": "Auth",
            "description": "Login & access validation"
        },
        {
            "name": "AI Agents",
            "description": "AI Agent management"
        },
        {
            "name": "Manage AI Agents",
            "description": "Manage AI Agents \"General, Voice & Language, Call handling, Intelligence settings\""
        },
        {
            "name": "General",
            "description": "General agent settings \"Prompt management\""
        },
        {
            "name": "Voice & Language",
            "description": "Voice & Language settings \"Models, Voices, Languages, Background sounds\""
        },
        {
            "name": "Call Handling",
            "description": "Call Handling settings \"Voicemail, Redial, Call time limits\""
        },
        {
            "name": "Intelligence",
            "description": "Intelligence settings \"Knowledge bases, Conversation, Pronunciation, Reminders, AutoRizz, Smooth Talk, Boosted Keywords\""
        },
        {
            "name": "Integration",
            "description": "GHL Integration settings \"Location, post-call field mappings, call status tags\""
        },
        {
            "name": "Advanced",
            "description": "Advanced agent settings \"Functions, Tools\""
        },
        {
            "name": "AI Numbers",
            "description": "AI Number management"
        },
        {
            "name": "AI Call History",
            "description": "AI call history & logs"
        },
        {
            "name": "Contacts",
            "description": "Contact management"
        },
        {
            "name": "Contact Notes",
            "description": "Contact notes management"
        },
        {
            "name": "Appointments",
            "description": "Contact appointment management"
        },
        {
            "name": "Conversations",
            "description": "Conversations contacts with conversation activity"
        },
        {
            "name": "Dashboard",
            "description": "Dashboard metrics & filters"
        },
        {
            "name": "Powerlists",
            "description": "Powerlist management"
        },
        {
            "name": "Template",
            "description": "SMS & Voice template management"
        },
        {
            "name": "Tags",
            "description": "Contact & Powerlist tag management"
        },
        {
            "name": "Disposition",
            "description": "Disposition management"
        },
        {
            "name": "Campaign",
            "description": "Voice & other campaign management"
        },
        {
            "name": "Pipeline",
            "description": "Pipeline boards, stages, location filter, and LeadConnector (GHL) pipeline sync. Linked LeadConnector calls use that location's token only; an agency/Company connection is exchanged to a location token automatically."
        },
        {
            "name": "Meta Ads",
            "description": "Marketing \u2192 Meta Ads: connections, assets, Instant (Lead) Forms, campaigns, ad sets, ads, creatives, media upload, duplicate, reporting, and Conversions API (Pixel ID + CAPI token, independent of Facebook OAuth). Everything is created PAUSED. Each ads call acts on one Facebook connection: send X-Meta-Connection (id from GET /connections) or omit it for the first active one. Connect/disconnect Facebook is not on this surface."
        },
        {
            "name": "Google Ads",
            "description": "Marketing \u2192 Google Ads: customers, campaigns, image upload, image ads, 7-day insights, Lead Forms. Same live Manager (REST v25). Connect/disconnect is not on this surface."
        },
        {
            "name": "Ads Manager",
            "description": "Marketing \u2192 Ads Manager: one campaign across the Meta, Google, TikTok, LinkedIn, and Snapchat accounts already connected. Launch, pause, resume, import, and creative upload. Connect/disconnect stays on each network page. Campaign ids in the path are the encrypted id from the summary."
        },
        {
            "name": "TikTok Ads",
            "description": "Marketing \u2192 TikTok Ads. Image and video upload is on this surface. Connect/disconnect is not."
        },
        {
            "name": "Snapchat Ads",
            "description": "Marketing \u2192 Snapchat Ads. Media upload and creative create are on this surface. Connect/disconnect is not."
        },
        {
            "name": "LinkedIn Ads",
            "description": "Marketing \u2192 LinkedIn Ads. Image upload and creative create are on this surface. Connect/disconnect is not."
        },
        {
            "name": "Lead Form",
            "description": "Marketing \u2192 Lead Form: hosted page, JS embed, and cURL ingest into a PowerList. Not ads Lead Forms (Meta/Google/TikTok/Snapchat/LinkedIn). Public POST /ingest/lead uses the form key, not this Bearer token."
        },
        {
            "name": "Texting registration",
            "description": "Register the business for texting (A2P 10DLC) end to end: business details, a compliance check of the website, consent and sample messages with exact fixes, submit, then a pipeline with expected timelines. Nothing is sent for review until the server-side check passes. Owners and admins change it; everyone can view."
        },
        {
            "name": "Carrier",
            "description": "Setup \u2192 Carrier application. Company or Admin only. GET company lists profile values that already match. Send legal_name, ein, entity, street, city, state, zip, or website when that field is empty. Entity must be a type the carrier accepts. Submit once. Send extra files only when status is info_requested."
        },
        {
            "name": "Knowledge Hub",
            "description": "Knowledge Hub courses & learning content"
        },
        {
            "name": "Workflow",
            "description": "Workflow automation list & manage workflows, including Appointment Status, GPT, If/Else GPT filters, enrollment history, and scheduled enroll"
        },
        {
            "name": "Settings",
            "description": "Company settings including OpenAI and Claude (used by the GPT / Claude workflow action) and the company's own Resend email account"
        },
        {
            "name": "Reports",
            "description": "Reports Call & SMS Reports"
        }
    ],
    "paths": {
        "/api/messages/threads/{contactId}/summary": {
            "get": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Read a factual contact recap and source coverage",
                "description": "Authenticated, tenant-scoped and ContactVisibility-authorized read. No inference, billing, sends, sync/backfill or derived AI profile reads. Local recorded text/chat/email history, shared call outcomes and notes only. Latest inbound/outbound are independent of detail caps. Exact recorded account/contact opportunity search returns all verified deals or an explicit unavailable state. Does not include cached/live unmirrored conversation messages, private transcripts/recordings, AI-agent calls, quoted email history or attachments. Body store status and excerpt_source distinguish verified text, HTML converted to text, empty/failed/absent/quoted-only/no-text previews. Token resolution can perform its existing credential refresh. Response is private, no-store; refreshed_at is request time, not stage/history freshness.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "contactId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "success=true, summary: contact_id, mode=recorded_overview, refreshed_at, recap (latest_reply/latest_follow_up/latest_call/newest, each a dated source entry or null), tags, local_stage, opportunities, opportunities_state, interactions, coverage and explicit limits. Entry fields: source/id/at/direction/status/subject/text/truncated/body_state/store_status/excerpt_source. Excerpts use a 400 Unicode-codepoint cap plus ellipsis; truncation comes from the same extraction. Local names are saved snapshots."
                    },
                    "401": {
                        "description": "Unauthenticated"
                    },
                    "404": {
                        "description": "Missing, deleted, other-tenant or unauthorized contact (including reassignment during read)"
                    },
                    "429": {
                        "description": "Rate limited"
                    }
                }
            }
        },
        "/api/dialer/numbers/{id}/incoming": {
            "get": {
                "tags": [
                    "Settings"
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Company-scoped incoming-call setup. External entries include schedule_slots and legacy fields."
                    },
                    "401": {
                        "description": "Authentication required."
                    },
                    "403": {
                        "description": "Only owner/admin may change routing."
                    },
                    "404": {
                        "description": "Number is not on this account."
                    },
                    "422": {
                        "description": "Invalid setup. Nothing saved for this number."
                    }
                },
                "summary": "Read incoming-call setup and availability slots",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Settings"
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Company-scoped incoming-call setup. External entries include schedule_slots and legacy fields."
                    },
                    "401": {
                        "description": "Authentication required."
                    },
                    "403": {
                        "description": "Only owner/admin may change routing."
                    },
                    "404": {
                        "description": "Number is not on this account."
                    },
                    "422": {
                        "description": "Invalid setup. Nothing saved for this number."
                    }
                },
                "summary": "Replace incoming-call setup",
                "description": "Owner/admin only, scoped to the signed-in company. Replaces the whole setup. Existing schedules change only when explicitly saved. Off-schedule outside phones are skipped; configured fallback still applies.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "mode"
                                ],
                                "properties": {
                                    "mode": {
                                        "type": "string",
                                        "enum": [
                                            "ai",
                                            "team",
                                            "rep",
                                            "several"
                                        ]
                                    },
                                    "team_id": {
                                        "type": "integer"
                                    },
                                    "user_id": {
                                        "type": "integer"
                                    },
                                    "user_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "externals": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "number"
                                            ],
                                            "properties": {
                                                "number": {
                                                    "type": "string",
                                                    "description": "Outside US/Canada phone number."
                                                },
                                                "label": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "maxLength": 60
                                                },
                                                "schedule_enabled": {
                                                    "type": "boolean",
                                                    "default": false
                                                },
                                                "schedule_timezone": {
                                                    "type": "string",
                                                    "example": "America/New_York",
                                                    "description": "IANA timezone shared by this phone's slots; daylight saving follows local wall time."
                                                },
                                                "schedule_slots": {
                                                    "type": "array",
                                                    "nullable": true,
                                                    "minItems": 0,
                                                    "maxItems": 50,
                                                    "items": {
                                                        "type": "object",
                                                        "required": [
                                                            "days",
                                                            "start",
                                                            "end"
                                                        ],
                                                        "properties": {
                                                            "days": {
                                                                "type": "array",
                                                                "minItems": 1,
                                                                "items": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "maximum": 6
                                                                },
                                                                "description": "0 Sunday through 6 Saturday. Overnight slots belong to their start day."
                                                            },
                                                            "start": {
                                                                "type": "string",
                                                                "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
                                                                "example": "13:00"
                                                            },
                                                            "end": {
                                                                "type": "string",
                                                                "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
                                                                "example": "14:00",
                                                                "description": "Exclusive. Must differ from start. Earlier end means overnight."
                                                            }
                                                        }
                                                    },
                                                    "description": "Any matching slot makes the phone available. Gaps stay unavailable. Empty requires schedule_all_days_off=true and means no availability. Null/omitted uses legacy schedule_days/start/end."
                                                },
                                                "schedule_all_days_off": {
                                                    "type": "boolean",
                                                    "default": false,
                                                    "description": "Explicitly allow an empty slot list to turn all days off."
                                                },
                                                "schedule_days": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "integer",
                                                        "minimum": 0,
                                                        "maximum": 6
                                                    }
                                                },
                                                "schedule_start": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "schedule_end": {
                                                    "type": "string",
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    },
                                    "ring_seconds": {
                                        "type": "integer",
                                        "minimum": 5,
                                        "maximum": 60
                                    },
                                    "order": {
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "order"
                                        ]
                                    },
                                    "then": {
                                        "type": "string",
                                        "enum": [
                                            "ai",
                                            "forward",
                                            "voicemail"
                                        ]
                                    },
                                    "fallback_agent_id": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/dialer/numbers/incoming/all": {
            "put": {
                "tags": [
                    "Settings"
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Company-scoped incoming-call setup. External entries include schedule_slots and legacy fields."
                    },
                    "401": {
                        "description": "Authentication required."
                    },
                    "403": {
                        "description": "Only owner/admin may change routing."
                    },
                    "404": {
                        "description": "Number is not on this account."
                    },
                    "422": {
                        "description": "Invalid setup. Nothing saved for this number."
                    }
                },
                "summary": "Apply an incoming-call setup to all matching account numbers",
                "description": "Explicit bulk write. Returns saved count and skipped numbers with reasons. Optional job: all, dialer, ai, texting.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "mode"
                                ],
                                "properties": {
                                    "mode": {
                                        "type": "string",
                                        "enum": [
                                            "ai",
                                            "team",
                                            "rep",
                                            "several"
                                        ]
                                    },
                                    "team_id": {
                                        "type": "integer"
                                    },
                                    "user_id": {
                                        "type": "integer"
                                    },
                                    "user_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "integer"
                                        }
                                    },
                                    "externals": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "number"
                                            ],
                                            "properties": {
                                                "number": {
                                                    "type": "string",
                                                    "description": "Outside US/Canada phone number."
                                                },
                                                "label": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "maxLength": 60
                                                },
                                                "schedule_enabled": {
                                                    "type": "boolean",
                                                    "default": false
                                                },
                                                "schedule_timezone": {
                                                    "type": "string",
                                                    "example": "America/New_York",
                                                    "description": "IANA timezone shared by this phone's slots; daylight saving follows local wall time."
                                                },
                                                "schedule_slots": {
                                                    "type": "array",
                                                    "nullable": true,
                                                    "minItems": 0,
                                                    "maxItems": 50,
                                                    "items": {
                                                        "type": "object",
                                                        "required": [
                                                            "days",
                                                            "start",
                                                            "end"
                                                        ],
                                                        "properties": {
                                                            "days": {
                                                                "type": "array",
                                                                "minItems": 1,
                                                                "items": {
                                                                    "type": "integer",
                                                                    "minimum": 0,
                                                                    "maximum": 6
                                                                },
                                                                "description": "0 Sunday through 6 Saturday. Overnight slots belong to their start day."
                                                            },
                                                            "start": {
                                                                "type": "string",
                                                                "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
                                                                "example": "13:00"
                                                            },
                                                            "end": {
                                                                "type": "string",
                                                                "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
                                                                "example": "14:00",
                                                                "description": "Exclusive. Must differ from start. Earlier end means overnight."
                                                            }
                                                        }
                                                    },
                                                    "description": "Any matching slot makes the phone available. Gaps stay unavailable. Empty requires schedule_all_days_off=true and means no availability. Null/omitted uses legacy schedule_days/start/end."
                                                },
                                                "schedule_all_days_off": {
                                                    "type": "boolean",
                                                    "default": false,
                                                    "description": "Explicitly allow an empty slot list to turn all days off."
                                                },
                                                "schedule_days": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "integer",
                                                        "minimum": 0,
                                                        "maximum": 6
                                                    }
                                                },
                                                "schedule_start": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "schedule_end": {
                                                    "type": "string",
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    },
                                    "ring_seconds": {
                                        "type": "integer",
                                        "minimum": 5,
                                        "maximum": 60
                                    },
                                    "order": {
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "order"
                                        ]
                                    },
                                    "then": {
                                        "type": "string",
                                        "enum": [
                                            "ai",
                                            "forward",
                                            "voicemail"
                                        ]
                                    },
                                    "fallback_agent_id": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "job": {
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "dialer",
                                            "ai",
                                            "texting"
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/dialer/music": {
            "get": {
                "tags": [
                    "Dialer"
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Private to the signed-in user, including within a company. No company/admin override.",
                "summary": "List my music",
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "401": {
                        "description": "Sign in required"
                    },
                    "404": {
                        "description": "Track not owned by this user or no longer present"
                    }
                }
            },
            "post": {
                "tags": [
                    "Dialer"
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Private to the signed-in user, including within a company. No company/admin override.",
                "summary": "Upload my private music",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "file"
                                ],
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "MP3, M4A, WAV, OGG or FLAC; maximum 20 MB. Content is inspected."
                                    },
                                    "title": {
                                        "type": "string",
                                        "maxLength": 100
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Saved privately"
                    },
                    "422": {
                        "description": "Invalid audio, title or size"
                    },
                    "200": {
                        "description": "Success"
                    },
                    "401": {
                        "description": "Sign in required"
                    },
                    "404": {
                        "description": "Track not owned by this user or no longer present"
                    }
                }
            }
        },
        "/api/dialer/music/{id}": {
            "delete": {
                "tags": [
                    "Dialer"
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Private to the signed-in user, including within a company. No company/admin override.",
                "summary": "Remove my track",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "401": {
                        "description": "Sign in required"
                    },
                    "404": {
                        "description": "Track not owned by this user or no longer present"
                    }
                }
            }
        },
        "/api/dialer/music/{id}/audio": {
            "get": {
                "tags": [
                    "Dialer"
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "description": "Private to the signed-in user, including within a company. No company/admin override.",
                "summary": "Read my audio using authenticated playback",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Private audio bytes; never cached or exposed through an anonymous/signed capability URL",
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Sign in required"
                    },
                    "404": {
                        "description": "Track not owned by this user or no longer present"
                    }
                }
            }
        },
        "/api/analytics/dialer/powerlists": {
            "get": {
                "tags": [
                    "Reports",
                    "Powerlists"
                ],
                "summary": "Read the paged PowerLists performance overview",
                "description": "Tenant and visible reps are derived from authentication. Includes zero-activity lists. Progress covers current non-removed contacts and recorded lifetime dialing in the same list; call performance, actual dialing reps and disposition-based bookings use the selected account-time-zone period. Bookings are distinct contacts with a positive booking disposition, NOT calendar confirmations. Saved call/list attribution is retained after contact moves. Null means unavailable, not zero. Rates require 10 dials and verified evidence. Read-only; never starts calls, sends messages, moves contacts or changes dispositions.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "range",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "all_time",
                                "today",
                                "yesterday",
                                "week",
                                "month",
                                "last_7",
                                "last_30",
                                "last_week",
                                "last_month",
                                "last_365",
                                "last_7_days",
                                "last_30_days"
                            ]
                        },
                        "description": "Default today. all_time includes all recorded history through today. Ignored when both from and to are supplied."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Inclusive start date in account time zone; supply together with to."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Inclusive end date. Maximum span 366 days."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 200
                        },
                        "description": "List-name search."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "All",
                                "Active",
                                "Inactive",
                                "Default"
                            ]
                        },
                        "description": "Status filter; does not widen list permissions."
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        },
                        "description": "Page number."
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 25
                        },
                        "description": "Maximum 100 lists per page."
                    },
                    {
                        "name": "user_id",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "description": "Optional visible-rep filter. Cannot widen team/self scope."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "success + data: scope, timezone, window, generated_at, records, pagination and metric definitions. Each record: id/name/status, contacts(total/dialed/remaining/dialed_pct), calls(dials/unique_contacts/connects/connect_rate/unverified_calls/last_dial_at), reps(actual dialers with the same call metrics), appointments and dispositions(label/contacts)."
                    },
                    "401": {
                        "description": "Authentication required."
                    },
                    "422": {
                        "description": "Invalid dates, filter or pagination."
                    },
                    "500": {
                        "description": "Reporting unavailable; no fabricated fallback numbers."
                    }
                }
            }
        },
        "/api/login": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Login",
                "description": "Authenticate with email/password and receive a Bearer token.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/LoginRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Login successful",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Login successful",
                                    "token": "eyJ..."
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Invalid credentials"
                    }
                }
            }
        },
        "/api/ai/agent/list": {
            "get": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "List AI Agents",
                "description": "Paginated list of AI agents for the company. Each agent has billing_activity (billed, calls, billed_minutes, last_call_at) from its connected calls in the period; meta.billing_summary counts billed / not_billed across the whole list.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated agents"
                    },
                    {
                        "description": "Invalid days or billing value"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "days",
                        "in": "query",
                        "required": false,
                        "description": "Billing period in days: 7, 30 (default), 90, or 0 for all time.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "billing",
                        "in": "query",
                        "required": false,
                        "description": "all (default), billed or none.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/timezones": {
            "get": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "List AI Agent Timezones",
                "description": "Returns all enabled timezones for the AI Agent General tab (same rows and order as the web Timezone dropdown: is_enabled = Yes, ordered by name). Each record includes a base64-encoded id for use in PATCH /api/ai/agent/update/{id} as ai_timezone_id, plus name, location, value, and iana (location/value as IANA-style path).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Timezones list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "NQ==",
                                            "name": "New York / EST / Miami, FL",
                                            "location": "America",
                                            "value": "New_York",
                                            "iana": "America/New_York"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/ai/agent/create": {
            "post": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Create AI Agent",
                "description": "Create a new AI agent.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Agent created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "agent_id": "agent_xxx",
                                        "agent_name": "Sales Agent"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateAgentRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/call-endpoint": {
            "get": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Get Call Endpoint",
                "description": "Returns the unique POST webhook URL and accepted JSON fields for this agent. POST that URL to start a call. Include call_mode=outbound (default, places the call) or call_mode=inbound (registers the call and returns dialSip). Extra contact fields in form_data are passed through with the call.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Endpoint info",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "endpoint": "https://example.com/webhooks/ai/create-phone-call/eyJpdiI6...",
                                        "Method": "POST",
                                        "form_data": [
                                            "phone_number",
                                            "first_name",
                                            "last_name",
                                            "ghl_contact_id",
                                            "override_agent_id",
                                            "call_mode=outbound (outbound/inbound)",
                                            "local_presence_number=No (Yes/No)"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "AI agent not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": true,
                        "description": "AI agent_id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/webhooks/ai/create-phone-call/{id}": {
            "post": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Create Phone Call",
                "description": "Same URL as AI Agents \u2192 Endpoints. Auth is the unique path token from GET /api/ai/agent/call-endpoint (no Bearer header). Same JSON body for outbound and inbound. outbound (default) places the call and returns call_id. inbound registers the call and also returns dialSip for telephony to bridge. Contact fields in the body are passed through as dynamic variables.",
                "security": [],
                "responses": [
                    {
                        "description": "Call created. Outbound returns call_id only. Inbound also includes dialSip.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "successfully make a call.",
                                    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent inactive or insufficient balance",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Agent is inactive."
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found, phone missing, or number not assigned",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Agent not found"
                                }
                            }
                        }
                    },
                    {
                        "description": "Failed to create call",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "message": "Failed to create call."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "message": "Failed to create call."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted agent token from GET /api/ai/agent/call-endpoint (the last path segment of endpoint).",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreatePhoneCallRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/get/{id}": {
            "get": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Get AI Agent",
                "description": "Retrieve a single AI agent by agent_id.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Agent details"
                    },
                    {
                        "description": "Unauthenticated"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/folders": {
            "get": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "List AI Agent Folders",
                "description": "Returns all folders for the company in sort_order (same ordering as the web AI Agents sidebar). Use the base64 encoded id in all other folder endpoints.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Folders list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "f_name": "My Folder",
                                                "sort_order": 1,
                                                "added_by": 1,
                                                "created_at": "2026-01-01T00:00:00.000000Z",
                                                "updated_at": "2026-01-01T00:00:00.000000Z"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/ai/agent/folders/create": {
            "post": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Create AI Agent Folder",
                "description": "Create a new folder for organizing AI agents. The folder is appended at the end of the sort order (same as clicking \"+ Add\" in the web sidebar).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Folder created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Folder created successfully",
                                    "data": {
                                        "id": "MQ==",
                                        "f_name": "Sales Agents",
                                        "sort_order": 1,
                                        "added_by": 1,
                                        "created_at": "2026-01-01T00:00:00.000000Z",
                                        "updated_at": "2026-01-01T00:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateAgentFolderRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/folders/update/{id}": {
            "put": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Update AI Agent Folder",
                "description": "Rename an existing AI agent folder. Use the base64 encoded id from List AI Agent Folders.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Folder updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Folder updated successfully",
                                    "data": {
                                        "id": "MQ==",
                                        "f_name": "Updated Folder Name",
                                        "sort_order": 1,
                                        "added_by": 1,
                                        "created_at": "2026-01-01T00:00:00.000000Z",
                                        "updated_at": "2026-01-01T00:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Folder not found"
                    },
                    {
                        "description": "Validation error / Invalid folder ID"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded folder ID (from GET /api/ai/agent/folders)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateAgentFolderRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/folders/delete/{id}": {
            "delete": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Delete AI Agent Folder",
                "description": "Delete an AI agent folder. All agents inside the folder will have their folder_id set to null (unassigned) \u00e2\u20ac\u201d agents themselves are not deleted.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Folder deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Folder deleted successfully"
                                }
                            }
                        }
                    },
                    {
                        "description": "Folder not found"
                    },
                    {
                        "description": "Invalid folder ID"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded folder ID (from GET /api/ai/agent/folders)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/folders/reorder": {
            "post": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Reorder AI Agent Folders",
                "description": "Update the sort order of all AI agent folders in one request. Send the full ordered array of folder IDs (base64 encoded from List AI Agent Folders) \u00e2\u20ac\u201d position 0 becomes sort_order 1, position 1 becomes sort_order 2, and so on. Accepts both base64 encoded IDs and numeric IDs.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Folders reordered",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Folders reordered successfully"
                                }
                            }
                        }
                    },
                    {
                        "description": "One or more folders not found"
                    },
                    {
                        "description": "Validation error / Invalid folder ID"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ReorderAgentFoldersRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/update/{id}": {
            "patch": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Update AI Agent",
                "description": "Update an existing AI agent by agent_id. Send only the fields you want to change: agent_name (also synced to voice provider), status (Active/Inactive), folder_id (base64 encoded from List AI Agent Folders \u00e2\u20ac\u201d send null to unassign), ai_timezone_id (integer or base64 id from List AI Agent Timezones).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Agent updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Agent updated successfully",
                                    "data": {
                                        "agent_id": "agent_xxx",
                                        "agent_name": "Updated Sales Agent",
                                        "status": "Active",
                                        "folder_id": "MQ==",
                                        "ai_timezone_id": 5
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Validation error"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateAgentRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/export/{agent_id}": {
            "get": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Export AI Agent",
                "description": "Export a full snapshot of an AI agent \u00e2\u20ac\u201d including agent config, prompt histories, API configurations, sender records, and widget config \u00e2\u20ac\u201d as a JSON object. The returned data key can be passed directly to the Import AI Agent endpoint to recreate the agent on any account.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Agent export data",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "filename": "Sales Agent_2026-04-12_10-00-00.json",
                                    "data": {
                                        "agentExportData": {
                                            "name": "Sales Agent",
                                            "config": {
                                                "llmConfig": {
                                                    "model": "gpt-4.1-mini",
                                                    "prompt": "..."
                                                }
                                            }
                                        },
                                        "localAgentData": [],
                                        "promptHistories": [],
                                        "apiConfigurations": [],
                                        "senderRecords": [],
                                        "widgetConfig": null,
                                        "export_timestamp": 1744000000,
                                        "export_version": "2.0"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Agent fetch error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/import": {
            "post": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Import AI Agent",
                "description": "Import an AI agent from a previously exported JSON snapshot. Pass the full data object from the Export AI Agent response as the agent_data field. Creates a new AI agent, then restores prompt histories, API configurations, sender records, and widget config. The imported agent name is suffixed with \"(Imported)\". GHL integrations and folder assignments are only restored when importing into the same company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Agent imported",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Agent imported successfully",
                                    "agent_id": "agent_new123"
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error \u00e2\u20ac\u201d missing agent export data"
                    },
                    {
                        "description": "External API error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ImportAgentRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/delete/{id}": {
            "delete": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Delete AI Agent",
                "description": "Permanently delete an AI agent by agent_id. This removes the agent and all related local records (prompt history, API config, senders, widget). Also unlinks the agent from any assigned AI numbers.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Agent deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Agent deleted successfully"
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/duplicate/{agent_id}": {
            "post": {
                "tags": [
                    "AI Agents"
                ],
                "summary": "Duplicate AI Agent",
                "description": "Clone an existing AI agent (same behavior as dashboard agent duplicate). Applies package billing / usage like creating a new agent, creates a new AI agent with the name suffixed \" Duplicate\", copies prompt history, API configurations, sender records, and widget settings. Does not copy phone number assignments.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Agent duplicated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Agent duplicated successfully",
                                    "data": {
                                        "agent_id": "agent_new123",
                                        "agent_name": "Sales Agent Duplicate"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id to duplicate (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/prompt/history/{agent_id}": {
            "get": {
                "tags": [
                    "General"
                ],
                "summary": "Get Agent Prompt History",
                "description": "Returns paginated list of saved prompt histories for an agent. The id field is Base64 encoded \u00e2\u20ac\u201d use it in the \"Default Prompt\" dropdown. Each record contains all prompt sections (project_instructions, prompt_greetings, prompt_character, etc.).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Prompt history list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": [
                                        {
                                            "id": 1,
                                            "prompt_name": "API_Update_2024-01-01 10:00:00",
                                            "project_instructions": "...",
                                            "prompt_greetings": null,
                                            "created_at": "2024-01-01T10:00:00"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 5,
                                        "current_page": 1,
                                        "per_page": 20,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 5
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 50, default 20)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/prompt/get/{prompt_id}": {
            "get": {
                "tags": [
                    "General"
                ],
                "summary": "Get Prompt by ID",
                "description": "Fetch full data of a single saved prompt by its Base64 encoded ID (from prompt history list). Use this for the PASTE button \u00e2\u20ac\u201d fetch the prompt data before applying it to the agent.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Prompt data",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "NQ==",
                                        "prompt_name": "API_Update_2024-01-01 10:00:00",
                                        "project_instructions": "...",
                                        "prompt_greetings": null,
                                        "prompt_character": null,
                                        "prompt_transfer_instr": null,
                                        "prompt_critical_instr": null,
                                        "prompt_custom_vars": null,
                                        "prompt_company_info": null,
                                        "prompt_script_flow": null,
                                        "prompt_call_flow": null,
                                        "prompt_objections": null,
                                        "prompt_appt_flow": null,
                                        "prompt_faq_base": null,
                                        "created_at": "2024-01-01T10:00:00"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Prompt not found"
                    },
                    {
                        "description": "Invalid prompt ID"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "prompt_id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded prompt ID (from GET /api/ai/agent/prompt/history/{agent_id})",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/prompt/apply-agents": {
            "get": {
                "tags": [
                    "General"
                ],
                "summary": "List AI Agents For Prompt Apply",
                "description": "Returns only AI agents for the \"Apply this prompt to other agents\" dropdown. Pass current_agent_id to exclude the source agent.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "AI agents list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": [
                                        {
                                            "id": "agent_other_123",
                                            "agent_id": "agent_other_123",
                                            "agent_name": "Outbound Agent",
                                            "text": "Outbound Agent"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "current_agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Optional source AI agent_id to exclude from the dropdown",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Optional search by agent name or agent_id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/prompt/apply-to-agents": {
            "post": {
                "tags": [
                    "General"
                ],
                "summary": "Apply Saved Prompt To AI Agents",
                "description": "Applies an existing saved prompt by prompt_id to selected AI agents. Use GET /api/ai/agent/prompt/history/{agent_id} or GET /api/ai/agent/prompt/get/{prompt_id} to get the prompt_id, and GET /api/ai/agent/prompt/apply-agents for target agents.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved prompt applied",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Saved prompt applied to selected agents",
                                    "data": {
                                        "prompt_id": "NQ==",
                                        "applied_agents": [
                                            {
                                                "agent_id": "agent_other_123",
                                                "agent_name": "Outbound Agent"
                                            }
                                        ],
                                        "skipped_agents": []
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Prompt not found"
                    },
                    {
                        "description": "Validation error"
                    },
                    {
                        "description": "External API error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "prompt_id",
                                    "agent_ids"
                                ],
                                "properties": {
                                    "prompt_id": {
                                        "type": "string",
                                        "example": "NQ==",
                                        "description": "Base64 prompt ID from prompt history, or numeric prompt ID."
                                    },
                                    "agent_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "agent_other_123"
                                        ],
                                        "description": "Target AI agent_ids only."
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/prompt/update": {
            "post": {
                "tags": [
                    "General"
                ],
                "summary": "Update Agent Prompt",
                "description": "Creates a new prompt for the AI agent identified by agentId and immediately activates it. The created prompt is also stored in the agent's prompt history. prompt_mode \"single\": only general_prompt is used. prompt_mode \"sectioned\": general_prompt plus any filled section fields are concatenated. If general_prompt is a full headed prompt (=== Title ===, ## Title:, #Title#), those headings are split into the matching section fields automatically, same as paste/upload on the agent page. Explicit section fields you send are kept.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Prompt updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Prompt updated successfully",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "mode": "sectioned"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Validation error / No LLM configured"
                    },
                    {
                        "description": "External API error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdatePromptRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/prompt/update/{prompt_id}": {
            "patch": {
                "tags": [
                    "General"
                ],
                "summary": "Update Saved Prompt by ID",
                "description": "Updates an existing saved prompt record (from prompt history) by its ID. Only the fields you send will be updated; any field you leave out stays unchanged. If prompt_mode is \"single\", all section fields are forced to null. If prompt_mode is \"sectioned\" and general_prompt contains headings, those headings are split into the matching section fields automatically. This does NOT push changes to the live agent. To activate a prompt, use POST /api/ai/agent/prompt/update.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved prompt updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Saved prompt updated successfully",
                                    "data": {
                                        "prompt_id": 5,
                                        "prompt_name": "My Updated Prompt"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Prompt not found"
                    },
                    {
                        "description": "Validation error / No fields provided"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "prompt_id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded prompt ID (from GET /api/ai/agent/prompt/history/{agent_id})",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateSavedPromptRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/prompt/delete/{prompt_id}": {
            "delete": {
                "tags": [
                    "General"
                ],
                "summary": "Delete Saved Prompt",
                "description": "Delete a single saved prompt by its Base64 encoded ID. Use the id from GET /api/ai/agent/prompt/history/{agent_id}. This is for the red delete button in the prompt history list.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Prompt deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Prompt deleted successfully"
                                }
                            }
                        }
                    },
                    {
                        "description": "Prompt not found"
                    },
                    {
                        "description": "Invalid prompt ID"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "prompt_id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded prompt ID (from GET /api/ai/agent/prompt/history/{agent_id})",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/ghl-locations": {
            "get": {
                "tags": [
                    "General"
                ],
                "summary": "List GHL Locations",
                "description": "Returns all GoHighLevel locations linked to the authenticated user \u00e2\u20ac\u201d same list as the GHL Location dropdown on the General tab. Use the locationId value when calling PATCH /api/ai/agent/general/{agent_id}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "GHL locations list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": 1,
                                            "locationId": "hbU9PklUNxdtFAVrehNb",
                                            "location_name": "Rizler Dev",
                                            "companyId": "cmp_xxx"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/ai/agent/general/{agent_id}": {
            "patch": {
                "tags": [
                    "General"
                ],
                "summary": "Update General Settings (GHL Location)",
                "description": "Saves the selected GHL location on the agent \u00e2\u20ac\u201d same as the GHL Location dropdown on the General tab. Send glocation_id: null to clear the assignment.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "General settings updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "General settings updated successfully",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "glocation_id": "hbU9PklUNxdtFAVrehNb"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Validation error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "glocation_id"
                                ],
                                "properties": {
                                    "glocation_id": {
                                        "type": "string",
                                        "nullable": true,
                                        "example": "hbU9PklUNxdtFAVrehNb",
                                        "description": "GoHighLevel locationId (from GET /api/ai/agent/ghl-locations). Send null to clear."
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/ghl-location-data/{agent_id}/{glocation_id}": {
            "get": {
                "tags": [
                    "General"
                ],
                "summary": "Get GHL Location Data",
                "description": "Fetches live GHL data for a selected location \u00e2\u20ac\u201d calendars, contact custom fields, and location tags. Call this when the GHL Location dropdown changes on the General tab to reload calendar options and field mappings.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "GHL location data",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "calendars": [
                                        {
                                            "id": "cal_xxx",
                                            "name": "Sales Calendar",
                                            "calendarType": "event"
                                        }
                                    ],
                                    "customFields": [
                                        {
                                            "id": "field_xxx",
                                            "name": "Call Summary",
                                            "fieldKey": "contact.call_summary",
                                            "dataType": "TEXT"
                                        }
                                    ],
                                    "locationTags": [
                                        {
                                            "id": "tag_xxx",
                                            "name": "answered"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "glocation_id",
                        "in": "path",
                        "required": true,
                        "description": "GoHighLevel locationId (from GET /api/ai/agent/general/ghl-locations)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/v2/manage/call-handling/{agent_id}": {
            "get": {
                "tags": [
                    "Call Handling"
                ],
                "summary": "Get V2 Call Handling Settings",
                "description": "V2 agents only. Returns call-handling settings, including ivr_detection for answering-machine voice recognition. voiceRecognitionEnabled is the Advanced voice-recognition switch. immediateDetection true decides faster and is less certain. voicemailHandling is hang_up or leave_message.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "V2 call handling settings",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "voicemail_option": true,
                                        "ivr_detection": {
                                            "voicemailHandling": "leave_message",
                                            "voiceRecognitionEnabled": true,
                                            "recognitionEngine": "advanced",
                                            "immediateDetection": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Agent fetch error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "V2 AI agent_id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/agent/v2/manage/call-handling/voicemail/{agent_id}": {
            "patch": {
                "tags": [
                    "Call Handling"
                ],
                "summary": "Update V2 Voicemail and Voice Recognition",
                "description": "V2 agents only. Same voicemail update, plus answering-machine voice recognition. Send only the fields you want to change. voiceRecognitionEnabled true turns on Advanced voice recognition and enables detection. recognitionEngine must be advanced. immediateDetection true is faster and less certain; false listens a few seconds. voicemailHandling hang_up ends the call; leave_message uses staticPhrase or voicemail_message_text, or additionalInstructions when the message type is smartV1 / prompt.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "V2 voicemail settings updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Voicemail settings updated successfully",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "enable_voicemail_detection": true,
                                        "voicemail_action_type": "hangup",
                                        "ivr_detection": {
                                            "voicemailHandling": "hang_up",
                                            "voiceRecognitionEnabled": true,
                                            "recognitionEngine": "advanced",
                                            "immediateDetection": false
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Validation error / unsupported recognition engine"
                    },
                    {
                        "description": "Agent update error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "V2 AI agent_id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateVoicemailSettingsRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/v1/manage/advanced/functions/appointment-checker/{agent_id}": {
            "get": {
                "tags": [
                    "Advanced"
                ],
                "summary": "Get AI Appointment Checker",
                "description": "Returns whether this agent skips an outbound call when the lead already has an appointment, and which appointments it blocks: upcoming, past, or all. Off by default, and an agent that is already on without a saved choice blocks upcoming appointments. A transferred lead is still skipped while the checker is on. Inbound calls and join-meeting calls are never blocked.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Appointment Checker",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "enabled": false,
                                        "block": "upcoming"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Advanced"
                ],
                "summary": "Update AI Appointment Checker",
                "description": "Saves the AI Appointment Checker switch in the appointments JSON. Send enabled true to block outbound calls, and block as upcoming, past, or all. Omit block to keep the saved choice, or upcoming when none is saved. Send enabled false to turn the check off. Inbound calls and join-meeting calls are not blocked.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Appointment Checker updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Appointment Checker updated successfully",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "enabled": true,
                                        "block": "upcoming"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Validation error (enabled is required; block must be upcoming, past, or all)"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateAppointmentCheckerRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/v2/manage/advanced/functions/appointment-checker/{agent_id}": {
            "get": {
                "tags": [
                    "Advanced"
                ],
                "summary": "Get AI Appointment Checker",
                "description": "Returns whether this agent skips an outbound call when the lead already has an appointment, and which appointments it blocks: upcoming, past, or all. Off by default, and an agent that is already on without a saved choice blocks upcoming appointments. A transferred lead is still skipped while the checker is on. Inbound calls and join-meeting calls are never blocked.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Appointment Checker",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "enabled": false,
                                        "block": "upcoming"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Advanced"
                ],
                "summary": "Update AI Appointment Checker",
                "description": "Saves the AI Appointment Checker switch in the appointments JSON. Send enabled true to block outbound calls, and block as upcoming, past, or all. Omit block to keep the saved choice, or upcoming when none is saved. Send enabled false to turn the check off. Inbound calls and join-meeting calls are not blocked.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Appointment Checker updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Appointment Checker updated successfully",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "enabled": true,
                                        "block": "upcoming"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Validation error (enabled is required; block must be upcoming, past, or all)"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateAppointmentCheckerRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/v2/manage/advanced/phone-numbers/pool/{agent_id}": {
            "get": {
                "tags": [
                    "Advanced"
                ],
                "summary": "Get V2 Number Pool",
                "description": "V2 directional assignments. Optional query direction=outbound|inbound|both (omission uses legacy pool scope, not explicit Both). Returns selected pool and all company numbers, including disabled conflicts with reason and selectable=false. Each has assignment (Outbound pool, Inbound, Both, or null), inbound_owner, outbound_owner, number_id, status, selected and selectable. An outbound pool may coexist with another agent owning inbound.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Number pool",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "direction": "both",
                                        "pool": [
                                            {
                                                "number_id": "MTIz",
                                                "phone_number": "+16304087965",
                                                "phone_number_pretty": "+1 (630) 408-7965",
                                                "spam_status": null,
                                                "selected": true,
                                                "selectable": true,
                                                "reason": null,
                                                "assignment": "Both",
                                                "inbound_owner": "agent_abc123",
                                                "outbound_owner": "agent_abc123",
                                                "status": "ready"
                                            }
                                        ],
                                        "available": [
                                            {
                                                "number_id": "MTIz",
                                                "phone_number": "+16304087965",
                                                "phone_number_pretty": "+1 (630) 408-7965",
                                                "spam_status": null,
                                                "selected": true,
                                                "selectable": true,
                                                "reason": null,
                                                "assignment": "Both",
                                                "inbound_owner": "agent_abc123",
                                                "outbound_owner": "agent_abc123",
                                                "status": "ready"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "V2 AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "outbound",
                                "inbound",
                                "both"
                            ]
                        }
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Advanced"
                ],
                "summary": "Update V2 Number Pool",
                "description": "Replaces only the explicit direction (outbound, inbound or both). Omission uses legacy pool scope and preserves retained directional shapes. Outbound saves never touch inbound/provider links; inbound saves never select outbound caller ID. Both edits complete pairs and leaves unrepresented partial/split assignments unchanged. Send number_ids: [] to clear that direction. Changed inbound links are synced to the provider; unchanged links and counters are preserved. Conflicting ownership is rejected before mutation. Provider failures are returned as warnings with success=false and failed numbers retain their saved assignment. Repeat saves are idempotent.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Number pool saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Number assignments saved.",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "direction": "both",
                                        "warnings": [],
                                        "pool": [
                                            {
                                                "number_id": "MTIz",
                                                "phone_number": "+16304087965",
                                                "phone_number_pretty": "+1 (630) 408-7965",
                                                "spam_status": null,
                                                "selected": true,
                                                "selectable": true,
                                                "reason": null,
                                                "assignment": "Both",
                                                "inbound_owner": "agent_abc123",
                                                "outbound_owner": "agent_abc123",
                                                "status": "ready"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Validation error or number not available for this pool"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "V2 AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateNumberPoolRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/agent/v2/manage/advanced/phone-numbers/pool/{agent_id}/unassign": {
            "post": {
                "tags": [
                    "Advanced"
                ],
                "summary": "Unassign V2 Pool Number",
                "description": "Idempotently removes only the requested direction for this agent. Defaults to both for compatibility. Other agents and the opposite direction remain untouched. Outbound-only removal makes zero provider changes; inbound removal unlinks incoming calls. Returns warnings with success=false if provider sync fails.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Number unassigned",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Number assignment removed.",
                                    "data": {
                                        "agent_id": "agent_abc123",
                                        "direction": "both",
                                        "warnings": [],
                                        "number": {
                                            "number_id": "MTIz",
                                            "phone_number": "+16304087965",
                                            "phone_number_pretty": "+1 (630) 408-7965",
                                            "spam_status": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid number_id format"
                    },
                    {
                        "description": "Agent not found, or number is not in this pool"
                    },
                    {
                        "description": "Validation error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "agent_id",
                        "in": "path",
                        "required": true,
                        "description": "V2 AI agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UnassignNumberPoolRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/number/list": {
            "get": {
                "tags": [
                    "AI Numbers"
                ],
                "summary": "List AI Numbers",
                "description": "Paginated list of AI phone numbers with spam protection status. Returns nickname, area_code, spam_status, has_spam_protection, renewal_at and assigned agent IDs.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated numbers",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "number_id": "MTIz",
                                            "phone_number": "+16304087965",
                                            "phone_number_pretty": "+1 (630) 408-7965",
                                            "nickname": "Sales Line",
                                            "area_code": 630,
                                            "spam_status": "Clean",
                                            "inbound_agent_id": "agent_abc123",
                                            "outbound_agent_id": null,
                                            "has_spam_protection": 1,
                                            "renewal_at": "2026-05-01 00:00:00",
                                            "updated_at": "2026-04-20 09:38:00"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/ai/number/available": {
            "get": {
                "tags": [
                    "AI Numbers"
                ],
                "summary": "List Available Numbers",
                "description": "Paginated merge of numbers available for agent assignment \u00e2\u20ac\u201d AI numbers with at least one open slot (inbound or outbound), plus Twilio/SIP `phone_numbers` rows not yet linked in `ai_numbers`. Same pagination contract as List AI Numbers.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated available numbers",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "number_id": "MTIz",
                                            "phone_number": "+16304087965",
                                            "phone_number_pretty": "+1 (630) 408-7965",
                                            "spam_status": "Clean",
                                            "source": "ai_numbers",
                                            "available_for": {
                                                "inbound": true,
                                                "outbound": false
                                            }
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/ai/number/get/{id}": {
            "get": {
                "tags": [
                    "AI Numbers"
                ],
                "summary": "Get AI Number",
                "description": "Retrieve a single AI number by base64-encoded ID. Includes spam protection status and assigned agent IDs.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Number details",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "number_id": "MTIz",
                                        "phone_number": "+16304087965",
                                        "phone_number_pretty": "+1 (630) 408-7965",
                                        "nickname": "Sales Line",
                                        "area_code": 630,
                                        "spam_status": "Clean",
                                        "inbound_agent_id": "agent_abc123",
                                        "outbound_agent_id": null,
                                        "has_spam_protection": 1,
                                        "renewal_at": "2026-05-01 00:00:00",
                                        "created_at": "2026-01-01 00:00:00",
                                        "updated_at": "2026-04-20 09:38:00"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID"
                    },
                    {
                        "description": "Number not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Number record ID (base64 encoded \u00e2\u20ac\u201d from List AI Numbers)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/number/search": {
            "get": {
                "tags": [
                    "AI Numbers"
                ],
                "summary": "Search Available Numbers",
                "description": "Search for available phone numbers via Twilio. Provider returns up to 20 candidates; the API paginates that result set with `per_page` (same envelope as List AI Numbers). Use each row's `phone_token` in POST /api/ai/number/purchase.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated provider search results",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "phone_token": "KzE2MzA0MDg3OTY1L0NoaWNhZ28vSUwvNjMwL1VTL2xvY2Fs",
                                            "phone_number": "+16304087965",
                                            "friendly_name": "+1 (630) 408-7965",
                                            "locality": "Chicago, IL, US",
                                            "capabilities": [
                                                "Voice",
                                                "SMS",
                                                "MMS"
                                            ]
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "No numbers found"
                    },
                    {
                        "description": "Credentials not configured / Validation error"
                    },
                    {
                        "description": "Provider API error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "provider",
                        "in": "query",
                        "required": true,
                        "description": "Provider to search (Twilio)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "area_code",
                        "in": "query",
                        "required": false,
                        "description": "Area code, region name, or city to search (e.g. 630, IL, Chicago)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "search_by",
                        "in": "query",
                        "required": false,
                        "description": "Search type: AreaCode (default), Region, or City",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "description": "ISO 2-letter country code (default: US)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "phone_type",
                        "in": "query",
                        "required": false,
                        "description": "Number type: local (default), tollfree, or mobile",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15) \u2014 slices the provider result set",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/ai/number/purchase": {
            "post": {
                "tags": [
                    "AI Numbers"
                ],
                "summary": "Purchase AI Number",
                "description": "Purchase a phone number selected from GET /api/ai/number/search. Pass the `phone_token` exactly as returned by the search endpoint. Automatically purchases via Twilio, sets up SIP trunk, assigns inbound/outbound agents, and charges billing usage.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Number purchased",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Number purchased successfully",
                                    "data": {
                                        "number_id": "MTIz",
                                        "phone_number": "+16304087965",
                                        "phone_number_pretty": "+16304087965",
                                        "nickname": "Sales Line",
                                        "provider": "Twilio",
                                        "inbound_agent_id": "agent_abc123",
                                        "outbound_agent_id": null
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Agent not found"
                    },
                    {
                        "description": "Validation error"
                    },
                    {
                        "description": "Failed to purchase number or SIP setup failed"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PurchaseNumberRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/number/update/{id}": {
            "patch": {
                "tags": [
                    "AI Numbers"
                ],
                "summary": "Update AI Number",
                "description": "Update the nickname and/or agent assignments (inbound/outbound) of an AI number. All fields are optional \u00e2\u20ac\u201d send only the fields you want to change. If a new agent_id is provided for inbound/outbound, any previous assignment of that agent on another number is automatically cleared.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Number updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Number updated successfully",
                                    "data": {
                                        "number_id": "MTIz",
                                        "phone_number": "+16304087965",
                                        "phone_number_pretty": "+1 (630) 408-7965",
                                        "nickname": "New Name",
                                        "inbound_agent_id": "agent_abc123",
                                        "outbound_agent_id": null
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid number_id"
                    },
                    {
                        "description": "Number or Agent not found"
                    },
                    {
                        "description": "Validation error"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Number record ID (base64 encoded \u00e2\u20ac\u201d from List AI Numbers)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateNumberRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/number/delete/{id}": {
            "delete": {
                "tags": [
                    "AI Numbers"
                ],
                "summary": "Delete AI Number",
                "description": "Permanently delete an AI number \u00e2\u20ac\u201d removes it from the voice provider (if applicable), resets SIP trunk routing, and deletes the local record.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Number deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Number deleted successfully"
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid number_id"
                    },
                    {
                        "description": "Number not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Number record ID (base64 encoded \u00e2\u20ac\u201d from List AI Numbers)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/number/assign": {
            "post": {
                "tags": [
                    "AI Numbers"
                ],
                "summary": "Assign Number to Agent",
                "description": "Assign an AI number to an agent as inbound or outbound. Any previous assignment of this agent on another number will be automatically cleared.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Number assigned",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Number assigned successfully",
                                    "data": {
                                        "number_id": "MTIz",
                                        "phone_number": "+16304087965",
                                        "agent_id": "agent_abc123",
                                        "type": "inbound"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid number_id"
                    },
                    {
                        "description": "Number or Agent not found"
                    },
                    {
                        "description": "Validation error"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AssignNumberRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/number/unassign": {
            "post": {
                "tags": [
                    "AI Numbers"
                ],
                "summary": "Unassign Number from Agent",
                "description": "Remove the inbound or outbound agent assignment from an AI number.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Number unassigned",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Number unassigned successfully",
                                    "data": {
                                        "number_id": "MTIz",
                                        "phone_number": "+16304087965",
                                        "type": "inbound"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid number_id"
                    },
                    {
                        "description": "Number not found"
                    },
                    {
                        "description": "No agent assigned / Validation error"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UnassignNumberRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/ai/number/spam-protect/{id}": {
            "post": {
                "tags": [
                    "AI Numbers"
                ],
                "summary": "Spam Protect Number",
                "description": "Add an AI number to spam protection via NumberVerifier. Requires a default TendLC profile to be configured for the company. Returns error if number is already protected.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Number added to spam protection",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Number added to spam protection successfully"
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid number_id"
                    },
                    {
                        "description": "Number not found"
                    },
                    {
                        "description": "Already protected or profile not configured"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Number record ID (base64 encoded \u00e2\u20ac\u201d from List AI Numbers)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/ai/call-history": {
            "get": {
                "tags": [
                    "AI Call History"
                ],
                "summary": "List AI Call History",
                "description": "Returns a paginated list of AI call history records for the authenticated company, ordered by most recent first. Supports multiple filters.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated AI call history",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "call_id": "call_abc123",
                                                "agent_id": "agent_xyz456",
                                                "ghl_contact_id": "ghl_001",
                                                "cost": 0.05,
                                                "call_duration": "00:02:35",
                                                "call_type": "web_call",
                                                "from_number": "+16304087965",
                                                "to_number": "+17735551234",
                                                "call_successful": "Yes",
                                                "hangup_reason": "user_hangup",
                                                "direction": "outbound",
                                                "call_summary": "Lead expressed interest in the product.",
                                                "call_transcript": "Agent: Hello...",
                                                "user_sentiment": "positive",
                                                "call_recording": "https://example.com/recordings/call_abc123.mp3",
                                                "contact_id": 42,
                                                "contact_name": "Jane Doe",
                                                "contact_url": "https://app.example.com/contacts/42/activity",
                                                "ghl_contact_url": "https://app.leadconnectorhq.com/v2/location/loc_001/contacts/detail/ghl_001",
                                                "pn_areacode": "630",
                                                "calendar_event_id": null,
                                                "appointment_date": null,
                                                "created_at": "2026-04-01T10:00:00Z"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 1,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter by agent_id (e.g. agent_abc123)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Filter from date (Y-m-d, e.g. 2026-04-01)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Filter to date (Y-m-d, e.g. 2026-04-30)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "description": "Call direction: inbound | outbound | web | All",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "user_sentiment",
                        "in": "query",
                        "required": false,
                        "description": "User sentiment: positive | negative | neutral | All",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "call_successful",
                        "in": "query",
                        "required": false,
                        "description": "Call successful: Yes | No | All",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "from_number",
                        "in": "query",
                        "required": false,
                        "description": "Filter by from number (partial match)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "to_number",
                        "in": "query",
                        "required": false,
                        "description": "Filter by to number (partial match)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "hangup_reason",
                        "in": "query",
                        "required": false,
                        "description": "Filter by hangup reason (e.g. user_hangup) | All",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "min_duration",
                        "in": "query",
                        "required": false,
                        "description": "Minimum call duration in seconds (e.g. 0)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "max_duration",
                        "in": "query",
                        "required": false,
                        "description": "Maximum call duration in seconds (e.g. 300 = 5 min, omit for no limit)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/contacts/fields": {
            "get": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Get Contact Fields",
                "description": "Returns company contact fields from Setup Contact Fields. Each item includes key, label, merge placeholder ({{contact.field}}), and custom default_value (empty string if none). Defaults are used only when that field is empty on the contact. Raw array, not { success, data }.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Array of contact fields",
                        "content": {
                            "application/json": {
                                "example": [
                                    {
                                        "key": "first_name",
                                        "label": "First Name",
                                        "placeholder": "{{contact.first_name}}",
                                        "default_value": "Dev"
                                    },
                                    {
                                        "key": "phone_number",
                                        "label": "Phone Number",
                                        "placeholder": "{{contact.phone_number}}",
                                        "default_value": ""
                                    }
                                ]
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            },
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Add Contact Field",
                "description": "Setup Contact Fields \u2192 Add. Creates a new contact column. Name: lowercase letters, numbers, underscore. Extra phones: phone_number1, phone_number2. Path: /api/contacts/fields.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Field created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Contact field created successfully.",
                                    "data": {
                                        "key": "lead_source",
                                        "label": "Lead Source",
                                        "length": 100
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not allowed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Not allowed."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid or reserved name",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Field name is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "example": "lead_source",
                                        "description": "Field name (name or fname)"
                                    },
                                    "ctype": {
                                        "type": "string",
                                        "example": "string",
                                        "description": "string | text | longtext"
                                    },
                                    "length": {
                                        "type": "integer",
                                        "example": 100
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Delete Contact Field",
                "description": "Setup Contact Fields \u2192 Delete. Removes a custom column and its saved default. Cannot delete phone_number, email, first_name, last_name, or other reserved fields. Path: /api/contacts/fields.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Field deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Contact field deleted successfully.",
                                    "data": {
                                        "key": "lead_source",
                                        "label": "Lead Source"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not allowed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Not allowed."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Field does not exist."
                                }
                            }
                        }
                    },
                    {
                        "description": "Protected field",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Field is required by the system and cannot be deleted."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "example": "lead_source",
                                        "description": "Field key to delete (name or fname)"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/field-folders": {
            "get": {
                "tags": [
                    "Contacts"
                ],
                "summary": "List Contact Field Folders",
                "description": "Company-scoped organization only. Returns folders and a field-key to folder-id assignments map. Fields without assignments are Unfiled. Requires view-contact-fields permission.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Organization",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "folders": [
                                            {
                                                "id": 1,
                                                "name": "Contact Info"
                                            }
                                        ],
                                        "assignments": {
                                            "email": 1
                                        },
                                        "field_order": [
                                            "phone_number",
                                            "email"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact Fields permission required"
                    },
                    {
                        "description": "Folder not found in your company"
                    },
                    {
                        "description": "Invalid name, duplicate name, or unknown field"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            },
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Create Contact Field Folder",
                "description": "Create an editable folder for the signed-in company only. No contact data is changed.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": 1,
                                        "name": "Contact Info"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact Fields permission required"
                    },
                    {
                        "description": "Folder not found in your company"
                    },
                    {
                        "description": "Invalid name, duplicate name, or unknown field"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 80,
                                        "example": "Contact Info"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/field-folders/{folder}": {
            "patch": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Rename Contact Field Folder",
                "description": "Rename only an owned folder. Existing field keys, values and integrations are unchanged.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Renamed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact Fields permission required"
                    },
                    {
                        "description": "Folder not found in your company"
                    },
                    {
                        "description": "Invalid name, duplicate name, or unknown field"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "folder",
                        "in": "path",
                        "required": true,
                        "description": "Folder id from the list endpoint",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 80,
                                        "example": "Contact Info"
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Remove Contact Field Folder",
                "description": "Remove only organization metadata. All fields in the folder become Unfiled; no fields or contact values are deleted.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Removed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Folder removed. Its fields are now Unfiled."
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact Fields permission required"
                    },
                    {
                        "description": "Folder not found in your company"
                    },
                    {
                        "description": "Invalid name, duplicate name, or unknown field"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "folder",
                        "in": "path",
                        "required": true,
                        "description": "Folder id from the list endpoint",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/contacts/field-folders/move": {
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Move Contact Fields to Folder",
                "description": "Move existing exact field keys to an owned folder, or folder_id:null for Unfiled. All keys are validated before writing. No contact values, defaults or integration mappings are changed.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Moved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact Fields permission required"
                    },
                    {
                        "description": "Folder not found in your company"
                    },
                    {
                        "description": "Invalid name, duplicate name, or unknown field"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "fields": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 500,
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "first_name",
                                            "email"
                                        ]
                                    },
                                    "folder_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "example": 1
                                    }
                                },
                                "required": [
                                    "fields",
                                    "folder_id"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/field-folders/reorder": {
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Reorder Contact Fields",
                "description": "Save the complete ordered list of exact visible field keys for the authenticated company. Contact views follow this order within existing folders. New fields append in their original order. Unknown, duplicate, hidden or missing fields reject the entire request. No contact values, defaults, folders, integration mappings, or contact-table schema are changed.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Order saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact Fields permission required"
                    },
                    {
                        "description": "Folder not found in your company"
                    },
                    {
                        "description": "Invalid name, duplicate name, or unknown field"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "fields": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 2048,
                                        "uniqueItems": true,
                                        "items": {
                                            "type": "string",
                                            "maxLength": 64
                                        },
                                        "example": [
                                            "last_name",
                                            "first_name",
                                            "phone_number",
                                            "email"
                                        ]
                                    }
                                },
                                "required": [
                                    "fields"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/fields/defaults": {
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Save Contact Field Defaults",
                "description": "Setup Contact Fields \u2192 Save Custom Default Values. Company-level fallbacks only \u2014 does not change contact records. Empty string removes that field\u2019s default. Unknown keys are ignored. Path: /api/contacts/fields/defaults.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Defaults saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Default values saved.",
                                    "data": [
                                        {
                                            "key": "first_name",
                                            "label": "First Name",
                                            "placeholder": "{{contact.first_name}}",
                                            "default_value": "Dev"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Not allowed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Not allowed."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid payload",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid defaults payload."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "defaults": {
                                        "type": "object",
                                        "additionalProperties": {
                                            "type": "string"
                                        },
                                        "example": {
                                            "first_name": "Dev",
                                            "phone_number": ""
                                        },
                                        "description": "Map of field key \u2192 default value. Empty string clears the default."
                                    }
                                },
                                "required": [
                                    "defaults"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/list": {
            "get": {
                "tags": [
                    "Contacts"
                ],
                "summary": "List Contacts",
                "description": "Paginated list of all contacts for the company. Optionally filter by PowerList using powerlist_id (Base64 encoded). To get available PowerList IDs use the GET /api/powerlists API.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated contacts list"
                    },
                    {
                        "description": "Invalid powerlist",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Invalid powerlist_id. Powerlist not found for your company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "powerlist_id",
                        "in": "query",
                        "required": false,
                        "description": "Optional. Base64 encoded PowerList ID to filter contacts by (from GET /api/powerlists API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/contacts/add": {
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Add Contact",
                "description": "Add or update a contact (upsert by phone_number). Used by Zapier and external integrations.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact added/updated"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AddContactRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/get/{id}": {
            "get": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Get Contact By ID",
                "description": "Retrieve a single contact record.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact object"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID (base64 encoded, returned from Add Contact API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/contacts/update/{id}": {
            "put": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Update Contact",
                "description": "Update an existing contact by its Base64 encoded ID. Only send the fields you want to update \u00e2\u20ac\u201d all other fields remain unchanged.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Contact updated successfully.",
                                    "contact": {
                                        "id": "MQ==",
                                        "first_name": "John",
                                        "last_name": "Doe",
                                        "phone_number": "+12025550100",
                                        "email_Address": "john.doe@example.com",
                                        "updated_at": "2026-04-06T10:00:00Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "No valid fields",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "No valid fields provided to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Contact ID (from List Contacts or Get Contact By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "first_name": {
                                        "type": "string",
                                        "example": "John"
                                    },
                                    "last_name": {
                                        "type": "string",
                                        "example": "Doe"
                                    },
                                    "phone_number": {
                                        "type": "string",
                                        "example": "+12025550100"
                                    },
                                    "email": {
                                        "type": "string",
                                        "example": "john.doe@example.com"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/delete/{id}": {
            "delete": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Delete Contact",
                "description": "Permanently delete a single contact by its Base64 encoded ID.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact deleted successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Contact deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Contact ID (from List Contacts or Get Contact By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/contacts/bulk-delete": {
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Bulk Delete Contacts",
                "description": "Permanently delete multiple contacts at once. Pass an array of Base64 encoded contact IDs.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contacts deleted successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Contacts deleted successfully.",
                                    "deleted_count": 3
                                }
                            }
                        }
                    },
                    {
                        "description": "No valid contacts found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "No valid contacts found for the provided IDs."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "ids array is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ids"
                                ],
                                "properties": {
                                    "ids": {
                                        "type": "array",
                                        "description": "Array of Base64 encoded contact IDs to delete",
                                        "items": {
                                            "type": "string",
                                            "example": "MQ=="
                                        },
                                        "example": [
                                            "MQ==",
                                            "Mg==",
                                            "Mw=="
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/{id}/memory": {
            "get": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Get Contact Memory",
                "description": "What AI Memory knows about this contact: the profile (summary, wants, concerns, next step), active facts, and the last 20 changes (who changed what). enabled=false means AI Memory is off for the account: nothing is built or used on calls and texts.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Memory",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "enabled": true,
                                        "profile": {
                                            "summary": "Owns a med spa, wants more bookings.",
                                            "wants": "More consults",
                                            "objections": "Price",
                                            "next_step": "Call Friday",
                                            "sentiment": "positive",
                                            "built_at": "2026-10-19 15:00:00",
                                            "locked_fields": [
                                                "summary"
                                            ]
                                        },
                                        "facts": [
                                            {
                                                "id": 12,
                                                "category": "budget",
                                                "text": "Budget around 5k",
                                                "source": "call",
                                                "source_ref": null,
                                                "confidence": 80,
                                                "pinned": false,
                                                "user_owned": false,
                                                "created_by": null,
                                                "edited_by": null,
                                                "created_at": "2026-10-19 15:00:00",
                                                "updated_at": "2026-10-19 15:00:00"
                                            }
                                        ],
                                        "events": [
                                            {
                                                "id": 7,
                                                "action": "add",
                                                "actor": "ai",
                                                "fact_id": 12,
                                                "before": null,
                                                "after": {
                                                    "id": 12,
                                                    "category": "budget",
                                                    "text": "Budget around 5k",
                                                    "source": "call",
                                                    "source_ref": null,
                                                    "confidence": 80,
                                                    "pinned": false,
                                                    "user_owned": false,
                                                    "created_by": null,
                                                    "edited_by": null,
                                                    "created_at": "2026-10-19 15:00:00",
                                                    "updated_at": "2026-10-19 15:00:00"
                                                },
                                                "created_at": "2026-10-19 15:00:00"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact (or fact) not found in this account",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID (numeric)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Edit Contact Memory Profile",
                "description": "Edit summary / wants / objections / next_step. Edited fields are locked so the AI rebuild keeps your words; pass unlock: [\"summary\"] to hand a field back to the AI. Returns the profile.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Profile",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "summary": "Decides with his wife.",
                                        "wants": null,
                                        "objections": null,
                                        "next_step": null,
                                        "sentiment": null,
                                        "built_at": null,
                                        "locked_fields": [
                                            "summary"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact (or fact) not found in this account",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID (numeric)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "summary": {
                                        "type": "string",
                                        "maxLength": 1200
                                    },
                                    "wants": {
                                        "type": "string",
                                        "maxLength": 500
                                    },
                                    "objections": {
                                        "type": "string",
                                        "maxLength": 500
                                    },
                                    "next_step": {
                                        "type": "string",
                                        "maxLength": 300
                                    },
                                    "unlock": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "summary",
                                                "wants",
                                                "objections",
                                                "next_step"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/{id}/memory/facts": {
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Add Contact Memory Fact",
                "description": "Add a fact your team knows. Facts written by a person are never changed by the AI. Max 30 active facts per contact.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Fact",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "source": "user",
                                        "user_owned": true,
                                        "created_by": 5,
                                        "id": 12,
                                        "category": "budget",
                                        "text": "Budget around 5k",
                                        "source_ref": null,
                                        "confidence": 80,
                                        "pinned": false,
                                        "edited_by": null,
                                        "created_at": "2026-10-19 15:00:00",
                                        "updated_at": "2026-10-19 15:00:00"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact (or fact) not found in this account",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Category must be one of: budget, decision_maker, timeline, pain, objection, preference, personal, other."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID (numeric)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "text",
                                    "category"
                                ],
                                "properties": {
                                    "text": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "example": "Budget around 5k"
                                    },
                                    "category": {
                                        "type": "string",
                                        "enum": [
                                            "budget",
                                            "decision_maker",
                                            "timeline",
                                            "pain",
                                            "objection",
                                            "preference",
                                            "personal",
                                            "other"
                                        ],
                                        "example": "budget"
                                    },
                                    "pinned": {
                                        "type": "boolean",
                                        "example": false,
                                        "description": "Pinned facts are shown first and the AI never changes them."
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/{id}/memory/facts/{factId}": {
            "patch": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Edit Contact Memory Fact",
                "description": "Change a fact's text or category, or pin / unpin it. An edited fact becomes your team's: the AI never overwrites it.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Fact",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "pinned": true,
                                        "user_owned": true,
                                        "edited_by": 5,
                                        "id": 12,
                                        "category": "budget",
                                        "text": "Budget around 5k",
                                        "source": "call",
                                        "source_ref": null,
                                        "confidence": 80,
                                        "created_by": null,
                                        "created_at": "2026-10-19 15:00:00",
                                        "updated_at": "2026-10-19 15:00:00"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact (or fact) not found in this account",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Keep a fact under 500 characters."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID (numeric)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "factId",
                        "in": "path",
                        "required": true,
                        "description": "Fact ID",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "text": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "example": "Budget around 5k"
                                    },
                                    "category": {
                                        "type": "string",
                                        "enum": [
                                            "budget",
                                            "decision_maker",
                                            "timeline",
                                            "pain",
                                            "objection",
                                            "preference",
                                            "personal",
                                            "other"
                                        ],
                                        "example": "budget"
                                    },
                                    "pinned": {
                                        "type": "boolean",
                                        "example": false,
                                        "description": "Pinned facts are shown first and the AI never changes them."
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Delete Contact Memory Fact",
                "description": "Remove a fact. The change log keeps who removed it and what it said.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "deleted": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact (or fact) not found in this account",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID (numeric)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "factId",
                        "in": "path",
                        "required": true,
                        "description": "Fact ID",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/contacts/{id}/memory/rebuild": {
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Rebuild Contact Memory",
                "description": "Rebuild the profile and facts from every channel now (normally this happens a couple of minutes after new activity). Each rebuild is billed as one AI Memory update. Limited to 10 a minute.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Queued",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "queued": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact (or fact) not found in this account",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "AI Memory is off",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "AI Memory is off for this account. Turn it on in AI Memory settings first."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID (numeric)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/contacts/{id}/memory/forget": {
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Forget Contact",
                "description": "Erase everything AI Memory knows about this contact: profile, facts, change history and voice-call memories. One \"forget_all\" entry (counts only) stays so the team can see it was done. Owners and admins only. Deleting a contact does this automatically.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Forgotten",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "profile": 1,
                                        "facts": 6,
                                        "events": 14,
                                        "voice_memories": 2
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not allowed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Only account owners and admins can erase a contact's memory."
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact (or fact) not found in this account",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID (numeric)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/contacts/bulk-tag-update": {
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Bulk Assign Tags to Contacts",
                "description": "Assign tags to multiple contacts at once. Pass an array of Base64 encoded contact IDs and an array of tag IDs. To get available tag IDs, use the GET /api/tags/contactTag API. Passing an empty tag_ids array will clear tags from all selected contacts.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Tags updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Tags updated successfully.",
                                    "updated_count": 3,
                                    "applied_tags": [
                                        {
                                            "id": "MQ==",
                                            "tag": "Hot Lead"
                                        },
                                        {
                                            "id": "Mg==",
                                            "tag": "Follow Up"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "No valid contacts found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "No valid contacts found for the provided IDs."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "ids array is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ids",
                                    "tag_ids"
                                ],
                                "properties": {
                                    "ids": {
                                        "type": "array",
                                        "description": "Array of Base64 encoded contact IDs (from List Contacts API)",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "MQ==",
                                            "Mg==",
                                            "Mw=="
                                        ]
                                    },
                                    "tag_ids": {
                                        "type": "array",
                                        "description": "Array of Base64 encoded tag IDs to assign. Use GET /api/tags/contactTag to get available tag IDs. Pass empty array [] to clear all tags.",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "MQ==",
                                            "Mg==",
                                            "Mw=="
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/bulk-powerlist-update": {
            "post": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Move Contacts to Another PowerList",
                "description": "Move multiple contacts to a different PowerList at once. Pass an array of Base64 encoded contact IDs and the target PowerList ID (Base64 encoded). PowerList capacity limits are automatically handled.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contacts moved successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Contacts moved to powerlist successfully.",
                                    "updated_count": 3,
                                    "powerlist_id": "MQ==",
                                    "powerlist_name": "Hot Leads"
                                }
                            }
                        }
                    },
                    {
                        "description": "No valid contacts found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "No valid contacts found for the provided IDs."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "powerlist_id is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ids",
                                    "powerlist_id"
                                ],
                                "properties": {
                                    "ids": {
                                        "type": "array",
                                        "description": "Array of Base64 encoded contact IDs to move (from List Contacts API)",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "MQ==",
                                            "Mg==",
                                            "Mw=="
                                        ]
                                    },
                                    "powerlist_id": {
                                        "type": "string",
                                        "description": "Base64 encoded target PowerList ID to move contacts into (from List Powerlists API)",
                                        "example": "Mg=="
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/logs/{id}": {
            "get": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Get Contact Logs",
                "description": "Returns a paginated list of all call/activity logs for a specific contact. The contact must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated contact logs",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "MQ==",
                                            "contact_id": "Mg==",
                                            "type": "Call",
                                            "direction": "outbound",
                                            "fromNo": "+12025550100",
                                            "toNo": "+13105550199",
                                            "status": "completed",
                                            "call_duration": "00:02:15",
                                            "recording_url": "https://example.com/recording.mp3",
                                            "user_sentiment": "positive",
                                            "created_at": "2026-04-01T10:00:00Z"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Contact ID (from List Contacts or Get Contact By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/contacts/notes/{id}": {
            "get": {
                "tags": [
                    "Contact Notes"
                ],
                "summary": "Get Contact Notes",
                "description": "Returns a paginated list of all notes for the given contact. The contact must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated contact notes",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "MQ==",
                                            "contact_id": 42,
                                            "added_by": 1,
                                            "note": "Called and left a voicemail.",
                                            "created_at": "2026-04-01T10:00:00Z",
                                            "updated_at": "2026-04-01T10:00:00Z"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Contact ID (from List Contacts or Get Contact By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/contacts/notes/add": {
            "post": {
                "tags": [
                    "Contact Notes"
                ],
                "summary": "Add Contact Note",
                "description": "Add a new note to a contact. contact_id must be base64 encoded.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Note added successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Note added successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "contact_id": 42,
                                        "added_by": 1,
                                        "note": "Called and left a voicemail.",
                                        "created_at": "2026-04-05T10:00:00Z",
                                        "updated_at": "2026-04-05T10:00:00Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "contact_id and note are required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AddContactNoteRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/notes/update/{id}": {
            "put": {
                "tags": [
                    "Contact Notes"
                ],
                "summary": "Update Contact Note",
                "description": "Update an existing note by its ID. The note must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Note updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Note updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "contact_id": 42,
                                        "added_by": 1,
                                        "note": "Updated note content.",
                                        "created_at": "2026-04-05T10:00:00Z",
                                        "updated_at": "2026-04-05T11:00:00Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Note not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Note not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "note is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Note ID (from Get Contact Notes API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateContactNoteRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/contacts/notes/delete/{id}": {
            "delete": {
                "tags": [
                    "Contact Notes"
                ],
                "summary": "Delete Contact Note",
                "description": "Permanently delete a note by its ID. The note must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Note deleted successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Note deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Note not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Note not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Note ID (from Get Contact Notes API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/contacts/notes/single/{id}": {
            "get": {
                "tags": [
                    "Contact Notes"
                ],
                "summary": "Get Single Note",
                "description": "Returns a single note by its note ID. The note must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Single contact note",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "id": "MQ==",
                                        "contact_id": 42,
                                        "added_by": 1,
                                        "note": "Called and left a voicemail.",
                                        "created_at": "2026-04-01T10:00:00Z",
                                        "updated_at": "2026-04-01T10:00:00Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Note not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Note not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Note ID (from Get Contact Notes API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/appointments/list": {
            "get": {
                "tags": [
                    "Appointments"
                ],
                "summary": "List Appointments",
                "description": "Returns a paginated list of appointments for the authenticated company. Optionally filter by contact_id or status.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated appointments",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "MQ==",
                                            "contact_id": 42,
                                            "title": "Appointment Booked by Dialer",
                                            "calendar": "Sales Calendar",
                                            "start_datetime": "2026-04-05 10:00:00",
                                            "end_datetime": "2026-04-05 10:30:00",
                                            "duration": "30 min",
                                            "location": "Zoom",
                                            "status": "confirmed",
                                            "booking_status": "confirmed",
                                            "is_booking": true,
                                            "google_meet_url": null,
                                            "created_at": "2026-04-01T10:00:00Z",
                                            "updated_at": "2026-04-01T10:00:00Z"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "contact_id",
                        "in": "query",
                        "required": false,
                        "description": "Optional \u00e2\u20ac\u201d Base64 encoded Contact ID to filter appointments for a specific contact",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Optional \u2014 Filter by status: pending (New) | confirmed | cancelled | completed (Showed) | rejected (Invalid) | no_show",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/appointments/get/{id}": {
            "get": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Get Appointment By ID",
                "description": "Retrieve a single appointment by its ID. Must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Appointment details",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "id": "MQ==",
                                        "contact_id": "Mg==",
                                        "calendar_id": "MQ==",
                                        "title": "Appointment Booked by Dialer",
                                        "description": null,
                                        "calendar": "Sales Calendar",
                                        "start_datetime": "2026-04-05 10:00:00",
                                        "end_datetime": "2026-04-05 10:30:00",
                                        "duration": "30 min",
                                        "location": "Zoom",
                                        "status": "confirmed",
                                        "booking_status": "confirmed",
                                        "is_booking": true,
                                        "booking_notes": null,
                                        "is_all_day": false,
                                        "reminder_minutes": null,
                                        "google_meet_url": null,
                                        "created_at": "2026-04-01T10:00:00Z",
                                        "updated_at": "2026-04-01T10:00:00Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Appointment not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Appointment not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Appointment ID (from List Appointments API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/appointments/calendars": {
            "get": {
                "tags": [
                    "Appointments"
                ],
                "summary": "List Calendars",
                "description": "Returns all active calendars for the authenticated company. Use the returned Base64 encoded id as calendar_id when creating an appointment.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Calendars list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "MQ==",
                                            "name": "Sales Calendar",
                                            "color": "#3b82f6",
                                            "type": "company",
                                            "allow_booking": true,
                                            "booking_type": "public",
                                            "description": null
                                        },
                                        {
                                            "id": "Mg==",
                                            "name": "Support Calendar",
                                            "color": "#10b981",
                                            "type": "personal",
                                            "allow_booking": false,
                                            "booking_type": null,
                                            "description": "Internal support team calendar"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/appointments/create": {
            "post": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Create Appointment",
                "description": "Create a new appointment or booking event linked to a contact and a calendar. Both calendar_id and contact_id must be Base64 encoded. The calendar must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Appointment created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Appointment created successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "contact_id": "Mg==",
                                        "calendar_id": "MQ==",
                                        "title": "Follow-up Call",
                                        "description": "Discuss pricing options",
                                        "calendar": "Sales Calendar",
                                        "start_datetime": "2026-05-01 10:00:00",
                                        "end_datetime": "2026-05-01 10:30:00",
                                        "duration": "30 min",
                                        "location": "Zoom",
                                        "status": "confirmed",
                                        "booking_status": "confirmed",
                                        "is_booking": true,
                                        "booking_notes": null,
                                        "is_all_day": false,
                                        "reminder_minutes": null,
                                        "google_meet_url": null,
                                        "created_at": "2026-04-20T10:00:00Z",
                                        "updated_at": "2026-04-20T10:00:00Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Calendar not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Calendar not found or does not belong to your company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "The end_datetime must be a date after start_datetime."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "calendar_id",
                                    "contact_id",
                                    "title",
                                    "start_datetime",
                                    "end_datetime"
                                ],
                                "properties": {
                                    "calendar_id": {
                                        "type": "string",
                                        "description": "Base64 encoded Calendar ID",
                                        "example": "MQ=="
                                    },
                                    "contact_id": {
                                        "type": "string",
                                        "description": "Base64 encoded Contact ID (from List Contacts API)",
                                        "example": "Mg=="
                                    },
                                    "title": {
                                        "type": "string",
                                        "description": "Appointment title",
                                        "example": "Follow-up Call"
                                    },
                                    "start_datetime": {
                                        "type": "string",
                                        "description": "Start datetime in UTC (Y-m-d H:i:s)",
                                        "example": "2026-05-01 10:00:00"
                                    },
                                    "end_datetime": {
                                        "type": "string",
                                        "description": "End datetime in UTC (Y-m-d H:i:s) \u00e2\u20ac\u201d must be after start_datetime",
                                        "example": "2026-05-01 10:30:00"
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "Optional description / notes",
                                        "example": "Discuss pricing options",
                                        "nullable": true
                                    },
                                    "location": {
                                        "type": "string",
                                        "description": "Optional location (address or meeting URL)",
                                        "example": "Zoom",
                                        "nullable": true
                                    },
                                    "is_booking": {
                                        "type": "boolean",
                                        "description": "True = booking, False = internal event (default: true)",
                                        "example": true
                                    },
                                    "is_all_day": {
                                        "type": "boolean",
                                        "description": "All-day event flag (default: false)",
                                        "example": false
                                    },
                                    "booking_notes": {
                                        "type": "string",
                                        "description": "Optional notes from the booker",
                                        "example": null,
                                        "nullable": true
                                    },
                                    "reminder_minutes": {
                                        "type": "integer",
                                        "description": "Reminder before event in minutes (e.g. 30)",
                                        "example": 30,
                                        "nullable": true
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/appointments/update/{id}": {
            "put": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Update Appointment",
                "description": "Update an existing appointment. Only send the fields you want to change \u00e2\u20ac\u201d all other fields remain unchanged. The appointment must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Appointment updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Appointment updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "contact_id": "Mg==",
                                        "calendar_id": "MQ==",
                                        "title": "Updated Title",
                                        "description": "Updated description",
                                        "calendar": "Sales Calendar",
                                        "start_datetime": "2026-05-02 11:00:00",
                                        "end_datetime": "2026-05-02 11:30:00",
                                        "duration": "30 min",
                                        "location": "Google Meet",
                                        "status": "confirmed",
                                        "booking_status": "confirmed",
                                        "is_booking": true,
                                        "booking_notes": null,
                                        "is_all_day": false,
                                        "reminder_minutes": 15,
                                        "google_meet_url": null,
                                        "created_at": "2026-04-20T10:00:00Z",
                                        "updated_at": "2026-04-21T08:00:00Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Appointment not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Appointment not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "No valid fields provided to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Appointment ID (from List Appointments API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "description": "Appointment title",
                                        "example": "Updated Title"
                                    },
                                    "description": {
                                        "type": "string",
                                        "description": "Description / notes",
                                        "example": "Updated description",
                                        "nullable": true
                                    },
                                    "start_datetime": {
                                        "type": "string",
                                        "description": "Start datetime in UTC (Y-m-d H:i:s)",
                                        "example": "2026-05-02 11:00:00"
                                    },
                                    "end_datetime": {
                                        "type": "string",
                                        "description": "End datetime in UTC (Y-m-d H:i:s)",
                                        "example": "2026-05-02 11:30:00"
                                    },
                                    "location": {
                                        "type": "string",
                                        "description": "Location or meeting URL",
                                        "example": "Google Meet",
                                        "nullable": true
                                    },
                                    "booking_notes": {
                                        "type": "string",
                                        "description": "Notes from the booker",
                                        "example": null,
                                        "nullable": true
                                    },
                                    "is_all_day": {
                                        "type": "boolean",
                                        "description": "All-day event flag",
                                        "example": false
                                    },
                                    "reminder_minutes": {
                                        "type": "integer",
                                        "description": "Reminder before event in minutes",
                                        "example": 15,
                                        "nullable": true
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/appointments/delete/{id}": {
            "delete": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Delete Appointment",
                "description": "Permanently delete an appointment by its Base64 encoded ID. The appointment must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Appointment deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Appointment deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Appointment not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Appointment not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Appointment ID (from List Appointments API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/appointments/status/{id}": {
            "put": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Update Appointment Status",
                "description": "Change the status of an appointment. Use \"approve\" or \"reject\" for bookings only. Use \"cancel\" for any future appointment. Use \"complete\" to mark any appointment as done.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Status updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Appointment approved successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "contact_id": "Mg==",
                                        "calendar_id": "MQ==",
                                        "title": "Follow-up Call",
                                        "description": null,
                                        "calendar": "Sales Calendar",
                                        "start_datetime": "2026-05-01 10:00:00",
                                        "end_datetime": "2026-05-01 10:30:00",
                                        "duration": "30 min",
                                        "location": "Zoom",
                                        "status": "confirmed",
                                        "booking_status": "confirmed",
                                        "is_booking": true,
                                        "booking_notes": null,
                                        "is_all_day": false,
                                        "reminder_minutes": null,
                                        "google_meet_url": null,
                                        "created_at": "2026-04-20T10:00:00Z",
                                        "updated_at": "2026-04-21T09:00:00Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Appointment not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Appointment not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Only bookings can be approved."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Appointment ID (from List Appointments API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "status"
                                ],
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "approve",
                                            "reject",
                                            "cancel",
                                            "complete"
                                        ],
                                        "description": "Action to perform: \"approve\" = confirm a pending booking | \"reject\" = reject a pending booking | \"cancel\" = cancel a future appointment | \"complete\" = mark as completed",
                                        "example": "approve"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/conversations/contacts": {
            "get": {
                "tags": [
                    "Conversations"
                ],
                "summary": "List Conversation Contacts",
                "description": "Returns a paginated list of contacts that have at least one conversation (call or SMS), ordered by most recent activity.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated conversation contacts",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "MQ==",
                                            "first_name": "John",
                                            "last_name": "Doe",
                                            "phone_number": "+12025550100",
                                            "email": "john.doe@example.com",
                                            "last_activity": "2026-04-05 14:32:00"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/conversations/contacts/search": {
            "get": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Search Contacts",
                "description": "Search contacts by name, phone number, or email. Returns a paginated list of matching contacts.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Matching contacts",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "MQ==",
                                            "first_name": "John",
                                            "last_name": "Doe",
                                            "phone_number": "+12025550100",
                                            "email": "john.doe@example.com"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Search query (name) is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "name",
                        "in": "query",
                        "required": true,
                        "description": "Search keyword \u00e2\u20ac\u201d name, phone, or email",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/conversations/contacts/{id}/disposition": {
            "put": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Update Contact Disposition",
                "description": "Update the disposition of a visible contact by its Base64 encoded ID. The disposition must belong to the authenticated company. Atomically moves the same contact to a unique matching stage within its current pipeline; without a pipeline, assigns only a unique account-wide match. Missing or ambiguous matches preserve the stage. Repeated saves do not duplicate pipeline membership or queued moves. Linked stage moves are queued for verified same-deal synchronization, never blind deal creation.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Disposition updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Disposition updated successfully.",
                                    "ghl_sync": {
                                        "state": "local_only",
                                        "reason": "not_linked"
                                    },
                                    "data": {
                                        "contact_id": "MQ==",
                                        "disposition_id": "Mw==",
                                        "disposition": "Not Interested",
                                        "pipe_stage_id": "NA==",
                                        "stage_changed": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "disposition_id is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Contact ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "disposition_id": {
                                        "type": "string",
                                        "example": "Mw==",
                                        "description": "Base64 encoded Disposition ID"
                                    }
                                },
                                "required": [
                                    "disposition_id"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/conversations/contacts/{id}/tags": {
            "put": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Update Contact Tags",
                "description": "Update the tags assigned to a contact. Pass an empty array to clear all tags. All tag IDs must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Tags updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "Tags updated successfully.",
                                    "data": {
                                        "contact_id": "MQ==",
                                        "applied_tags": [
                                            {
                                                "id": "MQ==",
                                                "tag": "Hot Lead"
                                            },
                                            {
                                                "id": "NA==",
                                                "tag": "Follow Up"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "One or more tag_ids are invalid."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Contact ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "tag_ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "MQ==",
                                            "NA=="
                                        ],
                                        "description": "Array of Base64 encoded tag IDs to assign. Pass empty array [] to clear all tags."
                                    }
                                },
                                "required": [
                                    "tag_ids"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/conversations/contacts/{id}/workflows": {
            "get": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Contact scheduled workflows",
                "description": "Messages sidebar: active + past workflow schedules for this contact (GHL-style date/time enroll). Path: /api/conversations/contacts/{id}/workflows.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Schedules",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "active": [
                                            {
                                                "id": 1,
                                                "kind": "schedule",
                                                "workflow_id": 2,
                                                "name": "No-show follow-up",
                                                "status": "scheduled",
                                                "scheduled_at": "Sep 20, 2026 9:30 AM",
                                                "can_cancel": true
                                            }
                                        ],
                                        "past": []
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID (numeric or route id)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Schedule workflow for contact",
                "description": "Enroll this contact into a workflow at a local date/time (user profile timezone). Trigger type on fire is scheduled_enrollment. Path: /api/conversations/contacts/{id}/workflows.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Scheduled",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Workflow scheduled for this contact."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The date field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ContactWorkflowScheduleRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/conversations/contacts/{id}/workflows/{scheduleId}": {
            "delete": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Cancel scheduled workflow",
                "description": "Remove a pending contact workflow schedule. Path: /api/conversations/contacts/{id}/workflows/{scheduleId}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Removed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Workflow removed from this contact."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "scheduleId",
                        "in": "path",
                        "required": true,
                        "description": "Schedule id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/conversations/contacts/{id}/dnd": {
            "put": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Update Contact DND",
                "description": "Set or clear the Do-Not-Disturb (DND) channels for a contact. Pass an empty array to remove all DND restrictions. Allowed values: DND-All, DND-Email, DND-SMS, DND-Call-Voicemail, DND-Inbound-Call-SMS.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "DND updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "DND updated successfully.",
                                    "data": {
                                        "contact_id": "MQ==",
                                        "dnd_types": [
                                            "DND-SMS",
                                            "DND-Call-Voicemail"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Invalid dnd_types value(s): DND-Unknown. Allowed: DND-All, DND-Email, DND-SMS, DND-Call-Voicemail, DND-Inbound-Call-SMS"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Contact ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "dnd_types": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "DND-All",
                                                "DND-Email",
                                                "DND-SMS",
                                                "DND-Call-Voicemail",
                                                "DND-Inbound-Call-SMS"
                                            ]
                                        },
                                        "example": [
                                            "DND-SMS",
                                            "DND-Call-Voicemail"
                                        ],
                                        "description": "DND channels to activate. Pass empty array [] to clear all DND."
                                    }
                                },
                                "required": [
                                    "dnd_types"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/conversations/calls": {
            "get": {
                "tags": [
                    "Conversations"
                ],
                "summary": "List Call Logs",
                "description": "Returns a paginated list of call logs across all contacts for the company. Supports optional search by contact name or phone number.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated call logs",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "Mg==",
                                            "contact_id": "MQ==",
                                            "contact_name": "John Doe",
                                            "phone_number": "+12025550100",
                                            "direction": "Outbound",
                                            "from_number": "+12052031593",
                                            "to_number": "+12025550100",
                                            "status": "Completed",
                                            "call_duration": "00:02:34",
                                            "recording_url": "https://cdn.example.com/recordings/abc.mp3",
                                            "sentiment": "Positive",
                                            "created_at": "2026-04-05 10:30:00"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/conversations/calls/search": {
            "get": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Search Call Logs",
                "description": "Search call logs by contact name or phone number. Returns a paginated list of matching call records.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Matching call logs",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "Mg==",
                                            "contact_id": "MQ==",
                                            "contact_name": "John Doe",
                                            "phone_number": "+12025550100",
                                            "direction": "Outbound",
                                            "from_number": "+12052031593",
                                            "to_number": "+12025550100",
                                            "status": "Completed",
                                            "call_duration": "00:02:34",
                                            "recording_url": "https://cdn.example.com/recordings/abc.mp3",
                                            "sentiment": "Positive",
                                            "created_at": "2026-04-05 10:30:00"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Search query (name) is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "name",
                        "in": "query",
                        "required": true,
                        "description": "Search keyword \u00e2\u20ac\u201d contact name or phone number",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/conversations/sms": {
            "get": {
                "tags": [
                    "Conversations"
                ],
                "summary": "List SMS Logs",
                "description": "Returns a paginated list of SMS messages across all contacts for the company. Supports optional search by contact name or phone number.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated SMS logs",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "Mg==",
                                            "contact_id": "MQ==",
                                            "contact_name": "John Doe",
                                            "phone_number": "+12025550100",
                                            "direction": "Outbound",
                                            "from_number": "+12052031593",
                                            "to_number": "+12025550100",
                                            "status": "Delivered",
                                            "message": "Hey, just following up!",
                                            "created_at": "2026-04-05 11:00:00"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Optional \u00e2\u20ac\u201d search by contact name or phone number",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/conversations/sms/search": {
            "get": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Search SMS Logs",
                "description": "Search SMS messages by contact name, phone number, or message content. Returns a paginated list of matching SMS logs.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Matching SMS logs",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "Mg==",
                                            "contact_id": "MQ==",
                                            "contact_name": "John Doe",
                                            "phone_number": "+12025550100",
                                            "direction": "Outbound",
                                            "from_number": "+12052031593",
                                            "to_number": "+12025550100",
                                            "status": "Delivered",
                                            "message": "Hey, just following up!",
                                            "created_at": "2026-04-05 11:00:00"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Search query (name) is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "name",
                        "in": "query",
                        "required": true,
                        "description": "Search keyword \u00e2\u20ac\u201d contact name, phone number, or message content",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/conversations/sms/send": {
            "post": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Send SMS to Contact",
                "description": "Send an outbound SMS to a contact using a 10DLC-linked from number. Message supports {{contact.field}} variables. to_number defaults to the contact's phone number if not provided.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "SMS sent successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "msg": "SMS sent successfully.",
                                    "data": {
                                        "contact_id": "MQ==",
                                        "from_number": "+12052031593",
                                        "to_number": "+12025550100",
                                        "provider": "Twilio"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "contact_id, message, and from_number are required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Send failed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Failed to send SMS: <provider error>"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "contact_id": {
                                        "type": "string",
                                        "example": "MQ==",
                                        "description": "Base64 encoded Contact ID"
                                    },
                                    "message": {
                                        "type": "string",
                                        "example": "Hi {{contact.first_name}}, just checking in!",
                                        "description": "SMS body. Supports {{contact.field}} variable substitution."
                                    },
                                    "from_number": {
                                        "type": "string",
                                        "example": "+12052031593",
                                        "description": "10DLC-linked sender phone number belonging to the company"
                                    },
                                    "to_number": {
                                        "type": "string",
                                        "example": "+12025550100",
                                        "description": "Recipient phone number. Defaults to contact's phone number if omitted."
                                    }
                                },
                                "required": [
                                    "contact_id",
                                    "message",
                                    "from_number"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/conversations/contacts/{id}/messages": {
            "get": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Contact Chat History",
                "description": "Returns full chat history (Calls + SMS combined) for a specific contact, sorted by latest activity. Optionally filter by type.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Combined chat history for the contact",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "contact": {
                                        "id": "MQ==",
                                        "first_name": "John",
                                        "last_name": "Doe",
                                        "phone_number": "+12025550100"
                                    },
                                    "data": [
                                        {
                                            "id": "Mg==",
                                            "contact_id": "MQ==",
                                            "type": "Call",
                                            "direction": "Outbound",
                                            "from_number": "+12052031593",
                                            "to_number": "+12025550100",
                                            "status": "Completed",
                                            "call_duration": 120,
                                            "recording_url": "https://example.com/recording.mp3",
                                            "sentiment": "Positive",
                                            "created_at": "2026-04-10 10:30:00"
                                        },
                                        {
                                            "id": "Mw==",
                                            "contact_id": "MQ==",
                                            "type": "SMS",
                                            "direction": "Outbound",
                                            "from_number": "+12052031593",
                                            "to_number": "+12025550100",
                                            "status": "Delivered",
                                            "message": "Hey, just following up!",
                                            "created_at": "2026-04-05 11:00:00"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 2,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 2
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "msg": "Contact not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Contact ID",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "description": "Optional filter: Call or SMS (omit to get both)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/powerlists": {
            "get": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "List Powerlists",
                "description": "Returns a paginated list of powerlists accessible to the authenticated user. Company admins get all powerlists; sub-users get only the powerlists they are assigned to.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated powerlists",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "name": "Cold Leads"
                                            },
                                            {
                                                "id": "Mg==",
                                                "name": "Hot Leads"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 2,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 2
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 100, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/powerlists/{id}": {
            "get": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Get Powerlist By ID",
                "description": "Retrieve full details of a single powerlist by its base64 encoded ID, including members, linked dispositions, tags, and contact fields.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Powerlist details",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "p_name": "Cold Leads",
                                        "status": "Active",
                                        "priority": "Medium",
                                        "disposition_call": "Yes",
                                        "call_timeout": "30",
                                        "dial_at_a_time": 1,
                                        "dail_max_daily": "2",
                                        "dail_total_max": "3",
                                        "max_contacts": 100,
                                        "ignore_dnc": "No",
                                        "dialed_reset_daily": "No",
                                        "contact_redial": "5 Minutes",
                                        "start_time": "09:00",
                                        "end_time": "17:00",
                                        "total_uploads": 250,
                                        "total_queued": 80,
                                        "total_deferred": 10,
                                        "total_removed": 5,
                                        "contact_fields": [
                                            "first_name",
                                            "last_name",
                                            "phone_number"
                                        ],
                                        "members": [
                                            {
                                                "id": "MQ==",
                                                "user_id": 3,
                                                "name": "Jane Smith",
                                                "email": "jane@example.com"
                                            }
                                        ],
                                        "dispositions": [
                                            {
                                                "id": "MQ==",
                                                "disposition_id": "MQ==",
                                                "disposition": "Appointment Set",
                                                "trigger": "end_call"
                                            }
                                        ],
                                        "tags": [
                                            {
                                                "id": "MQ==",
                                                "tag": "Priority"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid powerlist ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Powerlist ID (from List Powerlists API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/powerlists/upload-status": {
            "get": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Get Upload Status",
                "description": "Poll the background import progress using the queue_id returned by the Import Contacts API. Status values: pending (queued, not yet started), processing (actively importing), completed (finished successfully), failed (error occurred).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Upload status",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "queue_id": "powerlist_1_upload_1714000000_4321",
                                        "status": "completed",
                                        "updated_at": "2024-04-25 10:30:00",
                                        "result": {
                                            "total_processed": 500,
                                            "total_uploaded": 490,
                                            "total_skipped": 10,
                                            "powerlist_id": 1,
                                            "skip_reason": "Records skipped due to: 10 database duplicates and 0 file duplicates"
                                        },
                                        "error": null
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Upload status not found for the given queue_id."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "queue_id query parameter is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to get upload status."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "queue_id",
                        "in": "query",
                        "required": false,
                        "description": "Queue ID returned by the Import Contacts API",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/powerlists/upload-file": {
            "post": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Upload Powerlist File",
                "description": "Upload a CSV or Excel file and get back the file column headers along with available contact fields for field mapping. Send as multipart/form-data with the file under the `file` key. The returned `filepath` must be passed to the import/upload contacts API along with the field mapping.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "File uploaded successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "File uploaded successfully.",
                                    "filepath": "uploads/tmp/1714000000file.csv",
                                    "file_headers": [
                                        "First Name",
                                        "Last Name",
                                        "Phone Number",
                                        "Email"
                                    ],
                                    "contact_fields": [
                                        {
                                            "value": "first_name",
                                            "label": "First Name"
                                        },
                                        {
                                            "value": "last_name",
                                            "label": "Last Name"
                                        },
                                        {
                                            "value": "phone_number",
                                            "label": "Phone Number"
                                        },
                                        {
                                            "value": "email",
                                            "label": "Email"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "file is required and must be a valid CSV or Excel file."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to process uploaded file."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/UploadPowerlistFileRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/powerlists/create": {
            "post": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Create Powerlist",
                "description": "Create a new powerlist with optional members, dispositions, tags, and settings. All fields except name are optional and will use defaults when omitted. IMPORTANT: call_timeout must be one of: 15, 20, 25, 30, 35, 40, 45, 50, 55, 60. dail_total_max must be one of: 1, 3, 5, 10, 15, 20, 25, 30, Infinite. contact_redial must be one of: 5 Minutes, 10 Minutes, 15 Minutes, 30 Minutes, 45 Minutes, 1 Hour, 2 Hours, 3 Hours, 5 Hours, 12 Hours, 1 Day, 2 Days, 3 Days, 5 Days, 1 Week. next_powerlist_id must be base64 encoded (same as powerlist IDs). ai_agent must be the AI agent_id string (e.g. agent_abc123). members must be plain integer user IDs. dispositions.disposition_id must be base64 encoded.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Powerlist created successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Powerlist created successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "p_name": "Cold Leads",
                                        "status": "Active",
                                        "priority": "Medium",
                                        "disposition_call": "Yes",
                                        "call_timeout": "30",
                                        "dial_at_a_time": 1,
                                        "dail_max_daily": "2",
                                        "dail_total_max": "3",
                                        "max_contacts": 100,
                                        "next_powerlist_id": 2783,
                                        "ignore_dnc": "No",
                                        "dialed_reset_daily": "No",
                                        "contact_redial": "5 Minutes",
                                        "start_time": "09:00",
                                        "end_time": "17:00",
                                        "ai_agent": "agent_14d79e07d01accbba8acd4e174",
                                        "ai_agent_name": "My Sales Bot",
                                        "ghl_tag": null,
                                        "contact_fields": [
                                            "first_name",
                                            "last_name",
                                            "phone_number"
                                        ],
                                        "tags": [
                                            1,
                                            2
                                        ],
                                        "created_at": "2026-04-22T10:00:00Z",
                                        "updated_at": "2026-04-22T10:00:00Z",
                                        "members": [
                                            {
                                                "id": "MQ==",
                                                "user_id": 3,
                                                "name": "John Smith",
                                                "email": "john@example.com"
                                            }
                                        ],
                                        "dispositions": [
                                            {
                                                "id": "MQ==",
                                                "disposition_id": "OA==",
                                                "trigger": "end_call",
                                                "disposition": "Bad number / Wrong Number"
                                            },
                                            {
                                                "id": "Mg==",
                                                "disposition_id": "Mg==",
                                                "trigger": "answered",
                                                "disposition": "Interested"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "name is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to create powerlist."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreatePowerlistRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/powerlists/update/{id}": {
            "put": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Update Powerlist",
                "description": "Update an existing powerlist. All fields are optional \u00e2\u20ac\u201d only the fields you include will be updated. For members and dispositions, if the key is present the entire set is replaced (delete + re-insert). Same field rules as Create: call_timeout must be one of 15/20/25/30/35/40/45/50/55/60; dail_total_max must be one of 1/3/5/10/15/20/25/30/Infinite; contact_redial must be an exact allowed string; next_powerlist_id must be base64 encoded; ai_agent must be the AI agent_id string.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Powerlist updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Powerlist updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "p_name": "Hot Leads",
                                        "status": "Active",
                                        "priority": "High",
                                        "disposition_call": "Yes",
                                        "call_timeout": "30",
                                        "dial_at_a_time": 2,
                                        "dail_max_daily": "3",
                                        "dail_total_max": "5",
                                        "max_contacts": 200,
                                        "next_powerlist_id": 0,
                                        "ignore_dnc": "No",
                                        "dialed_reset_daily": "Yes",
                                        "contact_redial": "10 Minutes",
                                        "start_time": "09:00",
                                        "end_time": "17:00",
                                        "ai_agent": "agent_14d79e07d01accbba8acd4e174",
                                        "ai_agent_name": "My Sales Bot",
                                        "ghl_tag": null,
                                        "contact_fields": [
                                            "first_name",
                                            "last_name",
                                            "email_Address"
                                        ],
                                        "tags": [
                                            1,
                                            2
                                        ],
                                        "created_at": "2026-04-22T10:00:00Z",
                                        "updated_at": "2026-04-22T12:30:00Z",
                                        "members": [
                                            {
                                                "id": "MQ==",
                                                "user_id": 3,
                                                "name": "John Smith",
                                                "email": "john@example.com"
                                            }
                                        ],
                                        "dispositions": [
                                            {
                                                "id": "MQ==",
                                                "disposition_id": "MQ==",
                                                "trigger": "end_call",
                                                "disposition": "No Answer"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid powerlist ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update powerlist."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Powerlist ID (from List Powerlists API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdatePowerlistRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/powerlists/delete/{id}": {
            "delete": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Delete Powerlist",
                "description": "Permanently delete a powerlist and all its associated data: members, disposition links, and contacts. This action is irreversible.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Powerlist deleted successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Powerlist deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid powerlist ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete powerlist."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Powerlist ID (from List Powerlists API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/powerlists/{id}/status": {
            "patch": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Update Powerlist Status",
                "description": "Set a powerlist status to Active or Inactive.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Status updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Powerlist status updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "p_name": "Cold Leads",
                                        "status": "Inactive"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "status is required and must be Active or Inactive."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update powerlist status."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Powerlist ID (from List Powerlists API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PowerlistStatusRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/powerlists/{id}/duplicate": {
            "post": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Duplicate Powerlist",
                "description": "Clone an existing powerlist. Copies all settings, members, and dispositions \u00e2\u20ac\u201d contacts are NOT copied. The duplicate is named with a \" (Copy)\" suffix and set to Active status with all counters reset to zero.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Powerlist duplicated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Powerlist duplicated successfully.",
                                    "data": {
                                        "id": "Mg==",
                                        "p_name": "Cold Leads (Copy)",
                                        "status": "Active",
                                        "priority": "Medium",
                                        "disposition_call": "Yes",
                                        "call_timeout": "30",
                                        "dial_at_a_time": 1,
                                        "dail_max_daily": "2",
                                        "dail_total_max": "3",
                                        "max_contacts": 100,
                                        "total_uploads": 0,
                                        "total_queued": 0,
                                        "total_deferred": 0,
                                        "total_removed": 0,
                                        "contact_fields": [
                                            "first_name",
                                            "last_name",
                                            "phone_number"
                                        ],
                                        "tags": [
                                            1
                                        ],
                                        "created_at": "2026-04-22T11:00:00Z",
                                        "updated_at": "2026-04-22T11:00:00Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid powerlist ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to duplicate powerlist."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Powerlist ID to duplicate (from List Powerlists API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/powerlists/{id}/reset": {
            "post": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Reset Powerlist Contacts",
                "description": "Reset all contacts in a powerlist back to \"New\" status. No request body required. Returns the number of contacts that were reset.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contacts reset successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Powerlist contacts reset successfully.",
                                    "contacts_reset": 250
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid powerlist ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to reset powerlist."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Powerlist ID (from List Powerlists API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/powerlists/{id}/contacts/download": {
            "get": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Download Powerlist Contacts CSV",
                "description": "Download all contacts of a powerlist as a CSV file, grouped by disposition. Each group section shows the disposition name, total leads, column headers, and full contact rows. Summary rows at the top include total talk time, total contacts, and powerlist created time.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "CSV file download",
                        "content": {
                            "text/csv": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid powerlist ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to generate CSV."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Powerlist ID (from List Powerlists API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/powerlists/{id}/contacts/export": {
            "get": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Export Powerlist Contacts",
                "description": "Export raw contacts of a powerlist in the requested format. Use the format query parameter to choose excel (default), csv, or pdf. Each row contains all contact fields (system/ID fields excluded). Returns the file as a download attachment.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "File download (excel / csv / pdf)",
                        "content": {
                            "application/vnd.ms-excel": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            },
                            "text/csv": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            },
                            "application/octet-stream": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid format. Allowed: excel, csv, pdf."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to export contacts."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Powerlist ID (from List Powerlists API)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "required": false,
                        "description": "Export format: excel (default), csv, pdf",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/powerlists/{id}/import-contacts": {
            "post": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Import Contacts to Powerlist",
                "description": "Submit the filepath (from Upload Powerlist File API) and field mapping to start a background contact import. The fields_mapping keys must be formField0, formField1, ... in the same column order as the uploaded file. At least one column must be mapped to phone_number. Returns a queue_id to track import progress.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Import started",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Import started in background.",
                                    "queue_id": "powerlist_1_upload_1714000000_4321"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Mapping a phone number to the \"phone_number\" field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to start import."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Powerlist ID (from List Powerlists API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ImportContactsRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/powerlists/notes": {
            "get": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "List Powerlist Notes",
                "description": "Returns a paginated list of all notes across all powerlists for the company. Each record shows the note title, note content, associated powerlist name (PowerLists column), and created date.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated powerlist notes",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "title": "Follow up needed",
                                                "notes": "Call back on Monday to discuss pricing.",
                                                "powerlist_id": "MQ==",
                                                "powerlist_name": "Cold Leads",
                                                "created_at": "2026-04-23T10:00:00.000000Z"
                                            },
                                            {
                                                "id": "Mg==",
                                                "title": "Check back next week",
                                                "notes": "Send proposal email before calling.",
                                                "powerlist_id": "Mg==",
                                                "powerlist_name": "Hot Leads",
                                                "created_at": "2026-04-22T08:30:00.000000Z"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 2,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 2
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 100, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/powerlists/notes/{id}": {
            "get": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Get Single Powerlist Note",
                "description": "Retrieve a single powerlist note by its base64 encoded ID. Used to load form data for the Edit button.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Note details",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "title": "Follow up needed",
                                        "notes": "Call back on Monday to discuss pricing.",
                                        "powerlist_id": "MQ==",
                                        "powerlist_name": "Cold Leads",
                                        "created_at": "2026-04-23T10:00:00.000000Z",
                                        "updated_at": "2026-04-23T10:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Note not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid note ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Note ID (from List Powerlist Notes API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/powerlists/notes/create": {
            "post": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Create Powerlist Note",
                "description": "Create a new note for one or more powerlists. Pass powerlist_id as an array of base64 encoded IDs \u00e2\u20ac\u201d one note record is created per powerlist. Returns a single object if one powerlist_id is provided, or an array if multiple.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Note created successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Note created successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "company_id": 1,
                                        "added_by": 2,
                                        "title": "Follow up needed",
                                        "notes": "Call back on Monday to discuss pricing.",
                                        "powerlist_id": "MQ==",
                                        "created_at": "2026-04-23T10:00:00.000000Z",
                                        "updated_at": "2026-04-23T10:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist not found: MQ=="
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "title is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to create note."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreatePowerlistNoteRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/powerlists/notes/update/{id}": {
            "put": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Update Powerlist Note",
                "description": "Update an existing powerlist note by its base64 encoded ID. All fields are optional \u00e2\u20ac\u201d only send the fields you want to change. At least one field must be provided.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Note updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Note updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "company_id": 1,
                                        "added_by": 2,
                                        "title": "Follow up needed",
                                        "notes": "Call back on Tuesday instead.",
                                        "powerlist_id": "MQ==",
                                        "created_at": "2026-04-23T10:00:00.000000Z",
                                        "updated_at": "2026-04-23T11:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Note not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "No fields provided to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update note."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Note ID (from List Powerlist Notes API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdatePowerlistNoteRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/powerlists/notes/delete/{id}": {
            "delete": {
                "tags": [
                    "Powerlists"
                ],
                "summary": "Delete Powerlist Note",
                "description": "Permanently delete a powerlist note by its base64 encoded ID.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Note deleted successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Note deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthorized",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Unauthorized."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Note not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid note ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete note."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded Note ID (from List Powerlist Notes API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/template/sms": {
            "get": {
                "tags": [
                    "Template"
                ],
                "summary": "List SMS Templates",
                "description": "Returns a paginated list of SMS templates for the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated SMS templates",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": 1,
                                                "title": "Welcome Message",
                                                "template": "Hi {first_name}, welcome aboard!"
                                            },
                                            {
                                                "id": 2,
                                                "title": "Follow Up",
                                                "template": "Hi {first_name}, just following up!"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 2,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 2
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/template/sms/{id}": {
            "get": {
                "tags": [
                    "Template"
                ],
                "summary": "Get Single SMS Template",
                "description": "Returns a single SMS template by its Base64 encoded ID (from List SMS Templates).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "SMS template",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "title": "Welcome Message",
                                        "template": "Hi {first_name}, welcome aboard!"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "SMS template not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid template ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded SMS template ID (from List SMS Templates)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/template/sms/create": {
            "post": {
                "tags": [
                    "Template"
                ],
                "summary": "Create SMS Template",
                "description": "Creates a new SMS template for the authenticated company. Title must be unique per company (same as the web SMS Template screen).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "SMS template created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "SMS template created successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "title": "Welcome Message",
                                        "template": "Hi {first_name}, welcome aboard!"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation or duplicate title",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Welcome Message already exist."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "title",
                                    "template"
                                ],
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "example": "Welcome Message"
                                    },
                                    "template": {
                                        "type": "string",
                                        "example": "Hi {first_name}, welcome aboard!"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/template/sms/update/{id}": {
            "put": {
                "tags": [
                    "Template"
                ],
                "summary": "Update SMS Template",
                "description": "Updates an existing SMS template. Pass the Base64 encoded template ID (from List SMS Templates). Title must remain unique per company among other templates (same rules as the web SMS Template screen).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "SMS template updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "SMS template updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "title": "Welcome Message",
                                        "template": "Hi {first_name}, welcome aboard!"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "SMS template not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID, validation, or duplicate title",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid template ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded SMS template ID (from List SMS Templates)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "title",
                                    "template"
                                ],
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "maxLength": 150,
                                        "example": "Welcome Message"
                                    },
                                    "template": {
                                        "type": "string",
                                        "example": "Hi {first_name}, welcome aboard!"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/template/sms/delete/{id}": {
            "delete": {
                "tags": [
                    "Template"
                ],
                "summary": "Delete SMS Template",
                "description": "Permanently deletes an SMS template. Pass the Base64 encoded template ID (from List SMS Templates).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "SMS template deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "SMS template deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "SMS template not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid template ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded SMS template ID (from List SMS Templates)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/template/voice": {
            "get": {
                "tags": [
                    "Template"
                ],
                "summary": "List Voice Templates",
                "description": "Returns a paginated list of voice templates for the authenticated company. Sub-users only see their own templates.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated voice templates",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": 1,
                                                "title": "Intro Voicemail",
                                                "audio": "intro.mp3",
                                                "texttospeech": null,
                                                "status": "Active",
                                                "type": "audio"
                                            },
                                            {
                                                "id": 2,
                                                "title": "Follow Up",
                                                "audio": null,
                                                "texttospeech": "Hi, just following up!",
                                                "status": "Active",
                                                "type": "tts"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 2,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 2
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/template/voice/{id}": {
            "get": {
                "tags": [
                    "Template"
                ],
                "summary": "Get Single Voice Template",
                "description": "Returns a single voice template by its Base64 encoded ID (from List Voice Templates). Sub-users only access their own templates.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Voice template",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "title": "Intro Voicemail",
                                        "audio": "intro.mp3",
                                        "texttospeech": null,
                                        "status": "Active",
                                        "type": "audio"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Voice template not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid template ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice template ID (from List Voice Templates)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/template/voice/create": {
            "post": {
                "tags": [
                    "Template"
                ],
                "summary": "Create Voice Template",
                "description": "Creates a new voice template for the authenticated company. Send as multipart/form-data (required for file uploads). When type is text_to_speech, send title, type, and texttospeech. When type is audio_file or record_voice, send title, type, and the audio file under `audio` (MP3 or WAV). Title must be unique per company (same as the web Voice Template screen).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Voice template created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Voice template created successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "title": "Intro Voicemail",
                                        "audio": "https://example-bucket.s3.amazonaws.com/audio/1/fi1234567890le.mp3",
                                        "texttospeech": null,
                                        "status": "active",
                                        "type": "audio_file"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation, missing audio/text, or duplicate title",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Intro Voicemail already exist."
                                }
                            }
                        }
                    },
                    {
                        "description": "Storage error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to store audio file."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateVoiceTemplateRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/template/voice/update/{id}": {
            "post": {
                "tags": [
                    "Template"
                ],
                "summary": "Update Voice Template",
                "description": "Updates an existing voice template. Pass the Base64 encoded ID from List Voice Templates. Send as multipart/form-data. Same rules as create: text_to_speech requires texttospeech; audio_file/record_voice requires a stored audio URL or a new file under `audio`. Uploading a new audio file removes the previous file from storage when it was on S3. Sub-users may only update their own templates.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Voice template updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Voice template updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "title": "Intro Voicemail",
                                        "audio": "https://example-bucket.s3.amazonaws.com/audio/1/fi1234567890le.mp3",
                                        "texttospeech": null,
                                        "status": "active",
                                        "type": "audio_file"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Voice template not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID, validation, duplicate title, or missing audio/text",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid template ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Storage error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to store audio file."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice template ID (from List Voice Templates)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateVoiceTemplateRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/template/voice/delete/{id}": {
            "delete": {
                "tags": [
                    "Template"
                ],
                "summary": "Delete Voice Template",
                "description": "Permanently deletes a voice template. Pass the Base64 encoded template ID (from List Voice Templates). If the template had an audio file on S3, best-effort removal is attempted. Sub-users may only delete their own templates.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Voice template deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Voice template deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Voice template not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid template ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice template ID (from List Voice Templates)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/tags/contactTag": {
            "get": {
                "tags": [
                    "Tags"
                ],
                "summary": "List Contact Tags",
                "description": "Returns a paginated list of contact tags for the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated contact tags",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "tag": "Hot Lead"
                                            },
                                            {
                                                "id": "Mg==",
                                                "tag": "Follow Up"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 2,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 2
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/tags/contactTag/roles": {
            "get": {
                "tags": [
                    "Tags"
                ],
                "summary": "List Contact Tag Roles",
                "description": "Returns all roles for the authenticated company. Use the `id` values from this response as `role_view` entries when creating or updating a contact tag.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Company roles",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": [
                                        {
                                            "id": "MQ==",
                                            "title": "Sales Rep"
                                        },
                                        {
                                            "id": "Mg==",
                                            "title": "Manager"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/tags/contactTag/{id}/roles": {
            "get": {
                "tags": [
                    "Tags"
                ],
                "summary": "List Roles Assigned to Contact Tag",
                "description": "Returns the roles currently assigned to this contact tag (same rows you would get from the company list, filtered to this tag\u00e2\u20ac\u2122s `role_view`). `id` is the base64-encoded contact tag ID from List Contact Tags.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Assigned roles",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": [
                                        {
                                            "id": "MQ==",
                                            "title": "Sales Rep"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact tag not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid contact tag ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded contact tag ID (from List Contact Tags)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Tags"
                ],
                "summary": "Update Roles Assigned to Contact Tag",
                "description": "Replaces the `role_view` for this contact tag (same as editing roles on the full tag, without changing the tag name). Body: `role_view` = array of base64 role IDs from GET /api/tags/contactTag/roles. Send an empty array to clear all role restrictions.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Roles updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Contact tag roles updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "tag": "Hot Lead",
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact tag not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error or invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "One or more role IDs are invalid for your company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded contact tag ID (from List Contact Tags)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "role_view": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "MQ==",
                                            "Mg=="
                                        ],
                                        "description": "Base64 encoded role IDs from GET /api/tags/contactTag/roles. Use [] to clear."
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/tags/contactTag/create": {
            "post": {
                "tags": [
                    "Tags"
                ],
                "summary": "Create Contact Tag",
                "description": "Creates a new contact tag for the authenticated company (same as adding a tag on the Contact Tags page). `tag` is required (max 100 characters). Optionally pass `role_view`: an array of **base64 encoded** role IDs from GET /api/tags/contactTag/roles \u00e2\u20ac\u201d only those roles will see the tag; omit or send [] for no restriction. **Important:** the example `role_view` values in this spec (e.g. MQ==, Mg==) are illustrative only; they must exist for *your* company or you will get 422 \u00e2\u20ac\u201d always use ids returned by GET /api/tags/contactTag/roles.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact tag created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Contact tag created successfully.",
                                    "data": {
                                        "id": "MTIz",
                                        "tag": "Hot Lead",
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The tag field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "tag"
                                ],
                                "properties": {
                                    "tag": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "example": "Hot Lead",
                                        "description": "Label for the new contact tag"
                                    },
                                    "role_view": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "MQ==",
                                            "Mg=="
                                        ],
                                        "description": "Optional. Base64 encoded role IDs from GET /api/tags/contactTag/roles. Send [] or omit to allow all roles."
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/tags/contactTag/{id}": {
            "get": {
                "tags": [
                    "Tags"
                ],
                "summary": "Get Contact Tag",
                "description": "Returns a single contact tag by ID for the authenticated company. `role_view` contains base64 encoded role IDs (same format as GET /api/tags/contactTag/roles).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact tag detail",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "tag": "Hot Lead",
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact tag not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid contact tag ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded contact tag ID (from List Contact Tags)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Tags"
                ],
                "summary": "Update Contact Tag",
                "description": "Updates a contact tag and its `role_view` for the authenticated company. `tag` is required. Send `role_view` as an array of **base64 encoded** role IDs from GET /api/tags/contactTag/roles; send [] to clear all role restrictions.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact tag updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Contact tag updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "tag": "Hot Lead",
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact tag not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error or invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The tag field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded contact tag ID (from List Contact Tags)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "tag"
                                ],
                                "properties": {
                                    "tag": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "example": "Hot Lead",
                                        "description": "New label for the contact tag"
                                    },
                                    "role_view": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "MQ==",
                                            "Mg=="
                                        ],
                                        "description": "Base64 encoded role IDs from GET /api/tags/contactTag/roles. Send [] to clear restrictions."
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Tags"
                ],
                "summary": "Delete Contact Tag",
                "description": "Deletes a contact tag and its role assignments for the authenticated company (same as deleting on the Contact Tags page: removes `contact_tag_roles` first, then the tag).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact tag deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Contact tag deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Contact tag not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid contact tag ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded contact tag ID (from List Contact Tags)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/tags/powerlistTag": {
            "get": {
                "tags": [
                    "Tags"
                ],
                "summary": "List Powerlist Tags",
                "description": "Returns a paginated list of powerlist tags for the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated powerlist tags",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "tag": "Priority"
                                            },
                                            {
                                                "id": "Mg==",
                                                "tag": "Callback"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 2,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 2
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/tags/powerlistTag/create": {
            "post": {
                "tags": [
                    "Tags"
                ],
                "summary": "Create Powerlist Tag",
                "description": "Creates a new powerlist tag for the authenticated company. `tag` is required (max 100 characters). Optionally pass `role_view`: an array of **base64 encoded** role IDs from GET /api/tags/contactTag/roles \u00e2\u20ac\u201d only those roles will see the tag; omit or send [] for no restriction. **Important:** the example `role_view` values in this spec (e.g. MQ==, Mg==) are illustrative only; they must exist for *your* company or you will get 422 \u00e2\u20ac\u201d always use ids returned by GET /api/tags/contactTag/roles.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Powerlist tag created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Powerlist tag created successfully.",
                                    "data": {
                                        "id": "MTIz",
                                        "tag": "Priority",
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The tag field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "tag"
                                ],
                                "properties": {
                                    "tag": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "example": "Priority",
                                        "description": "Label for the new powerlist tag"
                                    },
                                    "role_view": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "MQ==",
                                            "Mg=="
                                        ],
                                        "description": "Optional. Base64 encoded role IDs from GET /api/tags/contactTag/roles. Send [] or omit to allow all roles."
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/tags/powerlistTag/{id}/roles": {
            "get": {
                "tags": [
                    "Tags"
                ],
                "summary": "List Roles Assigned to Powerlist Tag",
                "description": "Returns the roles currently assigned to this powerlist tag (same shape as List Roles Assigned to Contact Tag: `id` and `title` per row). `id` in the path is the base64-encoded powerlist tag ID from List Powerlist Tags.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Assigned roles",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": [
                                        {
                                            "id": "MQ==",
                                            "title": "Sales Rep"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist tag not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid powerlist tag ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded powerlist tag ID (from List Powerlist Tags)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Tags"
                ],
                "summary": "Update Roles Assigned to Powerlist Tag",
                "description": "Replaces the `role_view` for this powerlist tag (same as editing roles on the full tag, without changing the tag name). Body: `role_view` = array of base64 role IDs from GET /api/tags/contactTag/roles. Send an empty array to clear all role restrictions.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Roles updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Powerlist tag roles updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "tag": "Priority",
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist tag not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error or invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "One or more role IDs are invalid for your company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded powerlist tag ID (from List Powerlist Tags)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "role_view": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "MQ==",
                                            "Mg=="
                                        ],
                                        "description": "Base64 encoded role IDs from GET /api/tags/contactTag/roles. Use [] to clear."
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/tags/powerlistTag/{id}": {
            "get": {
                "tags": [
                    "Tags"
                ],
                "summary": "Get Powerlist Tag",
                "description": "Returns a single powerlist tag by ID for the authenticated company. `role_view` contains base64 encoded role IDs (same format as GET /api/tags/contactTag/roles).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Powerlist tag detail",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "tag": "Priority",
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist tag not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid powerlist tag ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded powerlist tag ID (from List Powerlist Tags)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Tags"
                ],
                "summary": "Update Powerlist Tag",
                "description": "Updates a powerlist tag and its `role_view` for the authenticated company. `tag` is required. Send `role_view` as an array of **base64 encoded** role IDs from GET /api/tags/contactTag/roles; send [] to clear all role restrictions.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Powerlist tag updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Powerlist tag updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "tag": "Priority",
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist tag not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error or invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The tag field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded powerlist tag ID (from List Powerlist Tags)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "tag"
                                ],
                                "properties": {
                                    "tag": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "example": "Priority",
                                        "description": "New label for the powerlist tag"
                                    },
                                    "role_view": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "example": [
                                            "MQ==",
                                            "Mg=="
                                        ],
                                        "description": "Base64 encoded role IDs from GET /api/tags/contactTag/roles. Send [] to clear restrictions."
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Tags"
                ],
                "summary": "Delete Powerlist Tag",
                "description": "Deletes a powerlist tag and its role assignments for the authenticated company (removes `powerlist_tag_roles` first, then the tag).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Powerlist tag deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Powerlist tag deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Powerlist tag not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid powerlist tag ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded powerlist tag ID (from List Powerlist Tags)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/disposition": {
            "get": {
                "tags": [
                    "Disposition"
                ],
                "summary": "List Dispositions",
                "description": "Returns a paginated list of dispositions for the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated dispositions",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "disposition": "Appointment Set",
                                                "status": "Active",
                                                "default_option": "Active",
                                                "select_text_color": "#FFFFFF",
                                                "select_bg_color": "#66FF00",
                                                "text_color": "#FFFFFF",
                                                "bg_color": "#0000FF",
                                                "call_status": "No"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 1,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Disposition"
                ],
                "summary": "Create Disposition",
                "description": "Creates a new disposition for the authenticated company (same as adding a disposition on Manage Dispositions). `disposition` is required (max 150 characters) and must be unique per company. Optional fields match the dispositions table: status, default_option, colors, call_status, GHL ids, optional exact opportunity pipeline/stage IDs, and `role_view` (base64 role IDs from GET /api/tags/contactTag/roles). Pipeline/stage IDs are configuration only and fail closed until provider readback/idempotency support exists.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Disposition created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Disposition created successfully.",
                                    "data": {
                                        "id": "MTI=",
                                        "disposition": "Appointment Set",
                                        "status": "Active",
                                        "default_option": "Active",
                                        "select_text_color": "#FFFFFF",
                                        "select_bg_color": "#66FF00",
                                        "text_color": "#FFFFFF",
                                        "bg_color": "#0000FF",
                                        "call_status": "No",
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The disposition field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to create disposition."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateDispositionRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/disposition/{id}/status": {
            "patch": {
                "tags": [
                    "Disposition"
                ],
                "summary": "Toggle Didn't Answer Button",
                "description": "Same as the **Setup Didn't Answer Button** column on Manage Dispositions. Updates the `status` field: **Default** = ON, **Active** = OFF. Only one disposition per company may have `status` = Default; enabling this one clears Default on all others (same as POST /manage/update-disposition-status). Optional body `{ \"enabled\": true|false }`; omit body to toggle.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Status updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "status": "Default",
                                        "didnt_answer_button_enabled": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Disposition not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID or validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid disposition ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update disposition."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded disposition ID (from List Dispositions)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PatchDispositionToggleRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/disposition/{id}/default-option": {
            "patch": {
                "tags": [
                    "Disposition"
                ],
                "summary": "Toggle Default Option",
                "description": "Same as the **Setup Default Option** column on Manage Dispositions. Updates the `default_option` field: **Default** = ON, **Active** = OFF. Only one disposition per company may have `default_option` = Default; enabling this one clears it on all others (same as POST /manage/update-disposition-default-option). Optional body `{ \"enabled\": true|false }`; omit body to toggle.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Default option updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "default_option": "Default",
                                        "default_option_enabled": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Disposition not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID or validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid disposition ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update disposition."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded disposition ID (from List Dispositions)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PatchDispositionToggleRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/disposition/{id}/call-status": {
            "patch": {
                "tags": [
                    "Disposition"
                ],
                "summary": "Update Call Status",
                "description": "Inline update for the **Call Status** dropdown on Manage Dispositions (same as updating `call_status` on the disposition record). Send JSON `{ \"call_status\": \"<value>\" }` where `<value>` must be exactly one of: **No**, **Ringing**, **Answered**, **Busy**, **Canceled**, **No-answer**, **In-Progress**, **Failed**, **AMD**, **Completed** \u2014 same set as GET /api/disposition/meta/call-status-options and the Manage Dispositions UI.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Call status updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Call status updated successfully",
                                    "data": {
                                        "id": "MQ==",
                                        "call_status": "Answered"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Disposition not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID or validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The call status field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update call status."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded disposition ID (from List Dispositions)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PatchDispositionCallStatusRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/disposition/{id}/roles": {
            "get": {
                "tags": [
                    "Disposition"
                ],
                "summary": "List Roles Assigned to Disposition",
                "description": "Returns roles linked to this disposition via `disposition_roles` (same as **role_view** on Create/Update/Get Disposition). Each item has base64 `id` and `title` \u00e2\u20ac\u201d same shape as GET /api/tags/contactTag/{id}/roles. `id` in the path is the base64 disposition ID from List Dispositions.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Assigned roles",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": [
                                        {
                                            "id": "MQ==",
                                            "title": "Sales Rep"
                                        },
                                        {
                                            "id": "Mg==",
                                            "title": "Manager"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Disposition not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid disposition ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded disposition ID (from List Dispositions)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Disposition"
                ],
                "summary": "Assign or Replace Disposition Roles",
                "description": "Replaces all `disposition_roles` rows for this disposition (same behaviour as sending **role_view** on PUT /api/disposition/{id}). Body must include `role_view`: array of base64 role IDs from GET /api/tags/contactTag/roles. Use `role_view: []` to clear. **Important:** example IDs in this spec are illustrative \u00e2\u20ac\u201d use values returned for your company or you will get 422.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Roles updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Disposition roles updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "disposition": "Appointment Set",
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Disposition not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "One or more role IDs are not valid for your company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update disposition roles."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded disposition ID (from List Dispositions)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateDispositionRolesRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/disposition/{id}": {
            "get": {
                "tags": [
                    "Disposition"
                ],
                "summary": "Get Disposition By ID",
                "description": "Returns one disposition by its base64 encoded ID (from List Dispositions or Create Disposition). Includes all fields needed to populate an edit form: labels, status, colors, call_status, GHL ids, optional opportunity pipeline/stage IDs, and `role_view` (base64 role IDs from GET /api/tags/contactTag/roles).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Disposition details",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "disposition": "Appointment Set",
                                        "status": "Active",
                                        "default_option": "Active",
                                        "select_text_color": "#FFFFFF",
                                        "select_bg_color": "#66FF00",
                                        "text_color": "#FFFFFF",
                                        "bg_color": "#0000FF",
                                        "call_status": "No",
                                        "ghl_accountid": null,
                                        "ghl_notecustid": null,
                                        "ghl_pipeline_id": null,
                                        "ghl_pipeline_stage_id": null,
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Disposition not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid disposition ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded disposition ID (from List Dispositions)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Disposition"
                ],
                "summary": "Update Disposition",
                "description": "Updates a disposition by base64 ID. Same JSON body as Create Disposition (`disposition` required). Send fields you want to change; omitted optional fields keep their current values. Include `role_view` to replace role assignments (array of base64 role IDs from GET /api/tags/contactTag/roles); omit `role_view` to leave roles unchanged. You may set GHL fields, including both opportunity pipeline/stage IDs, to null explicitly to clear them. Opportunity mappings remain unverified configuration and fail closed before provider mutation.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Disposition updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Disposition updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "disposition": "Appointment Set",
                                        "status": "Active",
                                        "default_option": "Active",
                                        "select_text_color": "#FFFFFF",
                                        "select_bg_color": "#66FF00",
                                        "text_color": "#FFFFFF",
                                        "bg_color": "#0000FF",
                                        "call_status": "No",
                                        "ghl_accountid": null,
                                        "ghl_notecustid": null,
                                        "ghl_pipeline_id": null,
                                        "ghl_pipeline_stage_id": null,
                                        "role_view": [
                                            "MQ==",
                                            "Mg=="
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Disposition not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The disposition field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update disposition."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded disposition ID (from List Dispositions)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateDispositionRequest"
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Disposition"
                ],
                "summary": "Delete Disposition",
                "description": "Deletes a disposition by base64 ID. Must belong to the authenticated company. Related `disposition_roles`, powerlist disposition links, and pipeline disposition links are removed via database cascade where applicable.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Disposition deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Disposition deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Disposition not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid disposition ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete disposition."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded disposition ID (from List Dispositions)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/disposition/meta/call-status-options": {
            "get": {
                "tags": [
                    "Disposition"
                ],
                "summary": "List Call Status Options",
                "description": "Returns every allowed `call_status` enum value for dispositions (same set as the Manage Dispositions Call Status dropdown and PATCH /api/disposition/{id}/call-status). Use this to populate client dropdowns without hard-coding.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Call status enum values",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "options": [
                                            "No",
                                            "Ringing",
                                            "Answered",
                                            "Busy",
                                            "Canceled",
                                            "No-answer",
                                            "In-Progress",
                                            "Failed",
                                            "AMD",
                                            "Completed"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/disposition/bulk-delete": {
            "post": {
                "tags": [
                    "Disposition"
                ],
                "summary": "Bulk Delete Dispositions",
                "description": "Deletes multiple disposition records in one request. Only dispositions owned by the authenticated company (`company_id`) are removed; foreign keys (`disposition_roles`, powerlist/pipeline links) cascade as for single DELETE. Invalid or other-company IDs are ignored; `deleted_count` is the number of rows actually removed.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Bulk delete result",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Dispositions deleted successfully.",
                                    "deleted_count": 3
                                }
                            }
                        }
                    },
                    {
                        "description": "None deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "No matching dispositions found for your company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "ids must be a non-empty array."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete dispositions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/BulkDeleteDispositionsRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/campaign/voice": {
            "get": {
                "tags": [
                    "Campaign"
                ],
                "summary": "List Voice Campaigns",
                "description": "Returns a paginated list of voice campaigns for the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated voice campaigns",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "title": "Cold Outreach",
                                                "status": "Active",
                                                "campaign_type": "ai",
                                                "start_date": "2026-04-01",
                                                "end_date": "2026-04-30",
                                                "start_time": "09:00",
                                                "end_time": "17:00"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 1,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Campaign"
                ],
                "summary": "Create Voice Campaign",
                "description": "Creates a new voice campaign for the authenticated company. Matches the manage Voice Campaign screen: title must be unique per company; status starts as pending. For campaign_type **ai**, set optional ai_agents (company AI agent row id) and calls_per_hour; agent routing is All. For **predictive**, set agent to All or Specific (with specific_agents when Specific), and optional **vm_id** (voice template id as Base64, same style as List Voice Templates; numeric string also works). A speed-dial row is created the same way as the web app. powerlist_id entries may be numeric IDs or Base64 as returned by List Powerlists.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Voice campaign created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Voice campaign created successfully.",
                                    "data": {
                                        "id": "Mg==",
                                        "title": "Cold Outreach",
                                        "company_id": 1,
                                        "status": "pending",
                                        "campaign_type": "ai"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "title field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to create voice campaign."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateVoiceCampaignRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/campaign/voice/{id}": {
            "get": {
                "tags": [
                    "Campaign"
                ],
                "summary": "Get Voice Campaign By ID",
                "description": "Returns a single voice campaign by Base64-encoded ID (same as List Voice Campaigns / create response). Includes all fields needed to prefill the manage edit form: title, powerlist_id, schedule, campaign_type, ai_agents, calls_per_hour, delay_in_call, agent, specific_agents, vm_id, weekdays, status, etc.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Voice campaign detail",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "company_id": 1,
                                        "added_by": 2,
                                        "title": "Cold Outreach",
                                        "powerlist_id": [
                                            1,
                                            2
                                        ],
                                        "start_time": "09:00:00",
                                        "end_time": "17:00:00",
                                        "start_date": "2026-04-01",
                                        "end_date": "2026-04-30",
                                        "status": "pending",
                                        "weekdays": [
                                            1,
                                            2,
                                            3,
                                            4,
                                            5
                                        ],
                                        "campaign_type": "ai",
                                        "being_dial": "No",
                                        "ai_agents": "5",
                                        "calls_per_hour": 100,
                                        "delay_in_call": 2,
                                        "agent": "All",
                                        "specific_agents": null,
                                        "vm_id": null,
                                        "created_at": "2026-04-01T10:00:00.000000Z",
                                        "updated_at": "2026-04-01T10:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Campaign not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid campaign ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice campaign ID (from List Voice Campaigns)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Campaign"
                ],
                "summary": "Delete Voice Campaign",
                "description": "Permanently deletes a voice campaign and its associated speed-dial record. Pass the Base64-encoded campaign ID (from List Voice Campaigns). The campaign must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Voice campaign deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Voice campaign deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Campaign not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid campaign ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete voice campaign."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice campaign ID (from List Voice Campaigns)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Campaign"
                ],
                "summary": "Update Voice Campaign",
                "description": "Fully updates an existing voice campaign by its Base64-encoded ID. All fields follow the same rules as Create Voice Campaign: title must be unique per company (excluding the current record); campaign_type switches the routing mode between ai and predictive. powerlist_id replaces the existing list. Passing null/empty to optional date/time fields clears them.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Voice campaign updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Voice campaign updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "company_id": 1,
                                        "added_by": 2,
                                        "title": "Cold Outreach Q2",
                                        "powerlist_id": [
                                            1,
                                            2
                                        ],
                                        "start_time": "09:00:00",
                                        "end_time": "17:00:00",
                                        "start_date": "2026-05-01",
                                        "end_date": "2026-05-31",
                                        "status": "pending",
                                        "weekdays": [
                                            1,
                                            2,
                                            3,
                                            4,
                                            5
                                        ],
                                        "campaign_type": "ai",
                                        "being_dial": "No",
                                        "ai_agents": "5",
                                        "calls_per_hour": 100,
                                        "delay_in_call": 2,
                                        "agent": "All",
                                        "specific_agents": null,
                                        "vm_id": null,
                                        "created_at": "2026-04-01T10:00:00.000000Z",
                                        "updated_at": "2026-05-01T08:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Campaign not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "title field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update voice campaign."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice campaign ID (from List Voice Campaigns)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateVoiceCampaignRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/campaign/voice/speed-dial/{setting_id}": {
            "delete": {
                "tags": [
                    "Campaign"
                ],
                "summary": "Delete Speed Dial Setting",
                "description": "Permanently deletes a single speed-dial row by its Base64-encoded ID (from Get Speed Dial Settings). The row must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Setting deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Speed-dial setting deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Speed-dial setting not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid speed-dial setting ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete speed-dial setting."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "setting_id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded speed-dial row ID (from Get Speed Dial Settings)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/campaign/voice/{id}/report": {
            "get": {
                "tags": [
                    "Campaign"
                ],
                "summary": "Get Voice Campaign Report",
                "description": "Returns a campaign report combining a summary of call stats (answered, no-answer, busy, voicemail, dropped rate) and a paginated list of call log records \u00e2\u20ac\u201d the same data shown on the Voice Campaign Report screen. Supports date range presets or custom date_from/date_to, status filter, direction filter, agent filter, min/max duration, and pagination.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Campaign report",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "campaign": {
                                            "id": "MQ==",
                                            "title": "Cold Outreach",
                                            "status": "inprogress"
                                        },
                                        "summary": {
                                            "answered": 42,
                                            "no_answer": 18,
                                            "busy": 5,
                                            "voicemail_count": 9,
                                            "dropped_rate": 2.5
                                        },
                                        "records": [
                                            {
                                                "id": 101,
                                                "from_number": "+12025550100",
                                                "to_number": "+13125550199",
                                                "status": "Completed",
                                                "direction": "Outbound",
                                                "type": "Call",
                                                "call_duration": "00:02:35",
                                                "call_duration_sec": 155,
                                                "transcription": "Hi, this is ...",
                                                "recording_url": "https://example.com/rec/abc.mp3",
                                                "user_id": 3,
                                                "created_at": "2026-04-27T10:05:00.000000Z",
                                                "first_name": "John",
                                                "last_name": "Doe"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 74,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 5,
                                            "from": 1,
                                            "to": 15
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Campaign not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid campaign ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice campaign ID (from List Voice Campaigns)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Preset date range: Today (default), Yesterday, Last 7 Days, Last 14 Days, Last 30 Days, This Month, Last Month, This Week Sun, This Week Mon, Last Week Sun, Last Week Mon, Last Business Week",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date Y-m-d. Used when date_range is omitted or Custom.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date Y-m-d.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filter by call status: All (default), Answered, Completed, Busy, No-answer, Failed, Missed Call, Cancel",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "description": "Filter by direction: All (default), Inbound, Outbound",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter by agent \u00e2\u20ac\u201d numeric or Base64 user ID. Omit or All for all agents.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "min_duration",
                        "in": "query",
                        "required": false,
                        "description": "Minimum call duration HH:MM:SS (default 00:00:00)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "max_duration",
                        "in": "query",
                        "required": false,
                        "description": "Maximum call duration HH:MM:SS or All for no limit (default All)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Records per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number (default 1)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/campaign/voice/{id}/speed-dial": {
            "get": {
                "tags": [
                    "Campaign"
                ],
                "summary": "Get Speed Dial Settings",
                "description": "Returns the speed-dial settings rows for a voice campaign, ordered by agent_count ascending. Each row contains the agent_count threshold and the calls-per-agent (cpa) value \u00e2\u20ac\u201d the same data shown on the Speed Dial modal in the manage Voice Campaign screen. Campaign must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Speed dial settings",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "campaign_id": "MQ==",
                                        "settings": [
                                            {
                                                "id": "MQ==",
                                                "company_id": 1,
                                                "added_by": 2,
                                                "campaign_id": 1,
                                                "agent_count": 1,
                                                "cpa": 12,
                                                "created_at": "2026-04-01T10:00:00.000000Z",
                                                "updated_at": "2026-04-01T10:00:00.000000Z"
                                            },
                                            {
                                                "id": "Mg==",
                                                "company_id": 1,
                                                "added_by": 2,
                                                "campaign_id": 1,
                                                "agent_count": 5,
                                                "cpa": 8,
                                                "created_at": "2026-04-01T10:00:00.000000Z",
                                                "updated_at": "2026-04-01T10:00:00.000000Z"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Campaign not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid campaign ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice campaign ID (from List Voice Campaigns)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Campaign"
                ],
                "summary": "Save Speed Dial Settings",
                "description": "Create or update speed-dial rows for a campaign in one call. Pass a **settings** array \u00e2\u20ac\u201d each item with an optional **id** (Base64 from Get Speed Dial Settings) for updating an existing row, or omit id to create a new row. agent_count and cpa are required for every item. Runs inside a transaction; any invalid row id rolls back the entire request. Returns the full updated settings list after save.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Settings saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Speed-dial settings saved successfully.",
                                    "new_settings": [
                                        {
                                            "id": "Mw==",
                                            "agent_count": 10,
                                            "cpa": 6
                                        }
                                    ],
                                    "data": {
                                        "campaign_id": "MQ==",
                                        "settings": [
                                            {
                                                "id": "MQ==",
                                                "company_id": 1,
                                                "added_by": 2,
                                                "campaign_id": 1,
                                                "agent_count": 1,
                                                "cpa": 12,
                                                "created_at": "2026-04-01T10:00:00.000000Z",
                                                "updated_at": "2026-04-01T10:00:00.000000Z"
                                            },
                                            {
                                                "id": "Mg==",
                                                "company_id": 1,
                                                "added_by": 2,
                                                "campaign_id": 1,
                                                "agent_count": 5,
                                                "cpa": 8,
                                                "created_at": "2026-04-01T10:00:00.000000Z",
                                                "updated_at": "2026-05-01T08:00:00.000000Z"
                                            },
                                            {
                                                "id": "Mw==",
                                                "company_id": 1,
                                                "added_by": 2,
                                                "campaign_id": 1,
                                                "agent_count": 10,
                                                "cpa": 6,
                                                "created_at": "2026-05-01T08:00:00.000000Z",
                                                "updated_at": "2026-05-01T08:00:00.000000Z"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Campaign not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The settings field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to save speed-dial settings."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice campaign ID (from List Voice Campaigns)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SpeedDialSaveRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/campaign/voice/{id}/pause": {
            "patch": {
                "tags": [
                    "Campaign"
                ],
                "summary": "Pause Voice Campaign",
                "description": "Sets the campaign status to **pause**. The campaign must currently be **inprogress**; any other state returns a 422. This mirrors the Pause button on the manage Voice Campaign screen. A paused campaign can be restarted via the Start endpoint.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Campaign paused",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Campaign paused successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "status": "pause"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Campaign not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid state",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Campaign can only be paused when its status is inprogress."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to pause voice campaign."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice campaign ID (from List Voice Campaigns)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/campaign/voice/{id}/start": {
            "patch": {
                "tags": [
                    "Campaign"
                ],
                "summary": "Start Voice Campaign",
                "description": "Sets the campaign status to **inprogress**. The campaign must currently be in **pending** or **pause** state; any other state returns a 422. This mirrors the Start button on the manage Voice Campaign screen.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Campaign started",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Campaign started successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "status": "inprogress"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Campaign not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid state",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Campaign can only be started when its status is pending or pause."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to start voice campaign."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded voice campaign ID (from List Voice Campaigns)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/pipeline": {
            "get": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "List Pipelines",
                "description": "Returns a paginated list of pipelines for the authenticated company. Matches the Pipeline page location filter: **all** (default), **unsynced** (Don't sync / not linked to LeadConnector), or a connected `locationId`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated pipelines",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "name": "Sales Pipeline",
                                                "ghl_location_id": "ve9EPM428h8vShlRW1KT",
                                                "ghl_pipeline_id": "VDm7RPYC2GLUvdpKmBfC",
                                                "linked_to_ghl": true,
                                                "stages_count": 4
                                            },
                                            {
                                                "id": "Mg==",
                                                "name": "Local Only",
                                                "ghl_location_id": null,
                                                "ghl_pipeline_id": null,
                                                "linked_to_ghl": false,
                                                "stages_count": 3
                                            }
                                        ],
                                        "pagination": {
                                            "total": 2,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 2
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "ghl_location_id",
                        "in": "query",
                        "required": false,
                        "description": "all (default), unsynced, or a LeadConnector locationId from GET /api/pipeline/ghl-locations",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/pipeline/ghl-locations": {
            "get": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "List Pipeline Location Filters",
                "description": "Filter options for the Pipeline board: All, Don't sync, then each connected LeadConnector location. Use `ghl_location_id` as GET /api/pipeline?ghl_location_id=. Connect/reconnect is not on this endpoint.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Location filters",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "ghl_location_id": "all",
                                                "label": "All",
                                                "is_default": false
                                            },
                                            {
                                                "ghl_location_id": "unsynced",
                                                "label": "Don't sync",
                                                "is_default": false
                                            },
                                            {
                                                "ghl_location_id": "ve9EPM428h8vShlRW1KT",
                                                "label": "Main Location",
                                                "is_default": true
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/pipeline/{id}": {
            "get": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Get Pipeline By ID",
                "description": "Retrieve a single pipeline by its ID, including stages (with ghl_stage_id when linked) and dispositions.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Pipeline details",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "name": "Sales Pipeline",
                                        "ghl_location_id": "ve9EPM428h8vShlRW1KT",
                                        "ghl_pipeline_id": "VDm7RPYC2GLUvdpKmBfC",
                                        "linked_to_ghl": true,
                                        "stages": [
                                            {
                                                "id": "MQ==",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "New Lead",
                                                "sorting_order": 0,
                                                "ghl_stage_id": "e93ba61a-53b3-45e7-985a-c7732dbcdb69"
                                            },
                                            {
                                                "id": "Mg==",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "Contacted",
                                                "sorting_order": 1,
                                                "ghl_stage_id": "a11ba61a-53b3-45e7-985a-c7732dbcdb70"
                                            }
                                        ],
                                        "dispositions": [
                                            {
                                                "id": "MQ==",
                                                "disposition": "Appointment Set"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Pipeline not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Pipeline not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid pipeline ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded pipeline ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Update Pipeline",
                "description": "Update a pipeline name. Optional ghl_location_id links an unlinked board; a linked location cannot be changed. Name/stage changes on a linked board are pushed to LeadConnector. Also available as PUT /api/pipeline/update/{id}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Pipeline updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Pipeline updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "name": "Updated Pipeline Name",
                                        "ghl_location_id": "ve9EPM428h8vShlRW1KT",
                                        "ghl_pipeline_id": "VDm7RPYC2GLUvdpKmBfC",
                                        "linked_to_ghl": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Pipeline not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Pipeline not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID or validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This pipeline is already linked to a GHL location and cannot be changed."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update pipeline."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded pipeline ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdatePipelineRequest"
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Delete Pipeline",
                "description": "Delete a pipeline and its stages. If the board is linked to LeadConnector, that LeadConnector pipeline (including deals on it) is deleted too. Also available as DELETE /api/pipeline/delete/{id}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Pipeline deleted successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Pipeline deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Pipeline not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Pipeline not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid pipeline ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete pipeline."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded pipeline ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/pipeline/stages/{id}": {
            "get": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Get Pipeline Stage By ID",
                "description": "Retrieve a single pipeline stage by its base64 encoded ID along with its paginated contacts. Validates that the stage belongs to a pipeline owned by the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Pipeline stage with contacts",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "stage": {
                                            "id": "MQ==",
                                            "pipeline_id": 1,
                                            "stage_name": "New Lead",
                                            "sorting_order": 1
                                        },
                                        "contacts": {
                                            "records": [
                                                {
                                                    "id": "MQ==",
                                                    "phone_number": "+16304087965",
                                                    "first_name": "John",
                                                    "last_name": "Doe",
                                                    "email_Address": "john@example.com",
                                                    "pipe_stage_id": 1,
                                                    "disposition_id": null
                                                }
                                            ],
                                            "pagination": {
                                                "total": 1,
                                                "current_page": 1,
                                                "per_page": 15,
                                                "last_page": 1,
                                                "from": 1,
                                                "to": 1
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Pipeline stage not found"
                    },
                    {
                        "description": "Invalid stage ID"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Get from Pipeline Stages API)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Contacts per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/pipeline/contact/move-stage": {
            "post": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Move Contact to Stage",
                "description": "Move a contact from one pipeline stage to another. Both contact_id and stage_id must be base64 encoded. If the pipeline is linked to LeadConnector and the contact is already linked there, a LeadConnector opportunity is created or moved to the matching stage.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact moved successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Contact moved to stage successfully.",
                                    "data": {
                                        "contact_id": "MQ==",
                                        "new_stage_id": "Mg==",
                                        "old_stage_id": "MQ==",
                                        "new_stage_count": 5,
                                        "old_stage_count": 3
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Contact or Stage not found"
                    },
                    {
                        "description": "Validation error \u2014 missing or invalid IDs"
                    },
                    {
                        "description": "Server error"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MoveContactStageRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/pipeline/stage/load-more-contacts": {
            "get": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Load More Stage Contacts",
                "description": "Offset-based load-more for contacts in a pipeline stage. Use offset + limit to implement infinite scroll \u00e2\u20ac\u201d pass the next offset equal to the number of records already loaded.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Next batch of contacts",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "stage_id": "MQ==",
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "phone_number": "+16304087965",
                                                "first_name": "John",
                                                "last_name": "Doe",
                                                "pipe_stage_id": 1
                                            },
                                            {
                                                "id": "Mg==",
                                                "phone_number": "+17735551234",
                                                "first_name": "Jane",
                                                "last_name": "Smith",
                                                "pipe_stage_id": 1
                                            }
                                        ],
                                        "offset": 10,
                                        "limit": 10,
                                        "loaded": 2,
                                        "total": 12,
                                        "has_more": false
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Stage not found"
                    },
                    {
                        "description": "stage_id missing or invalid"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "stage_id",
                        "in": "query",
                        "required": true,
                        "description": "Stage ID (required)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "required": false,
                        "description": "Number of records already loaded \u00e2\u20ac\u201d start from 0 (default 0)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Number of records to return (default 10, max 30)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/pipeline/create": {
            "post": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Create Pipeline",
                "description": "Create a new pipeline with optional stage names. Optional ghl_location_id creates the same board and stages on that connected LeadConnector location. Omit it (Don't sync) to keep the board local.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Pipeline created successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Pipeline created successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "name": "Sales Pipeline",
                                        "company_id": 1,
                                        "added_by": 1,
                                        "created_at": "2025-11-03T10:00:00Z",
                                        "updated_at": "2025-11-03T10:00:00Z",
                                        "stages": [
                                            {
                                                "id": "MQ==",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "New Lead",
                                                "sorting_order": 0,
                                                "created_at": "2025-11-03T10:00:00Z",
                                                "updated_at": "2025-11-03T10:00:00Z"
                                            },
                                            {
                                                "id": "Mg==",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "Contacted",
                                                "sorting_order": 1,
                                                "created_at": "2025-11-03T10:00:00Z",
                                                "updated_at": "2025-11-03T10:00:00Z"
                                            },
                                            {
                                                "id": "Mw==",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "Qualified",
                                                "sorting_order": 2,
                                                "created_at": "2025-11-03T10:00:00Z",
                                                "updated_at": "2025-11-03T10:00:00Z"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "name is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to create pipeline."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreatePipelineRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/pipeline/update/{id}": {
            "put": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Update Pipeline (alias)",
                "description": "Same as PUT /api/pipeline/{id}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Pipeline updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Pipeline updated successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Pipeline not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Pipeline not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID or validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "name is required and must not be empty."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded pipeline ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdatePipelineRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/pipeline/delete/{id}": {
            "delete": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Delete Pipeline (alias)",
                "description": "Same as DELETE /api/pipeline/{id}. Linked LeadConnector boards are deleted there too.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Pipeline deleted successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Pipeline deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Pipeline not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Pipeline not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid pipeline ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded pipeline ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/pipeline/{id}/contacts": {
            "get": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "List Pipeline Contacts",
                "description": "Returns a paginated list of all contacts across every stage of the given pipeline. Optionally filter by a specific stage (stage_id) or by assigned user (assigned_to). Each contact record includes a stage object showing which stage it belongs to. Contacts with is_deleted_id = Yes are excluded.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated pipeline contacts",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "pipeline_id": "MQ==",
                                        "pipeline_name": "Sales Pipeline",
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "first_name": "John",
                                                "last_name": "Doe",
                                                "phone_number": "+16304087965",
                                                "email_Address": "john@example.com",
                                                "pipe_stage_id": 1,
                                                "disposition_id": null,
                                                "assignto_id": null,
                                                "cstatus_id": "Answered",
                                                "created_at": "2025-11-01T10:00:00Z",
                                                "updated_at": "2025-11-02T08:00:00Z",
                                                "stage": {
                                                    "id": "MQ==",
                                                    "stage_name": "New Lead",
                                                    "sorting_order": 0
                                                }
                                            }
                                        ],
                                        "pagination": {
                                            "total": 1,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Pipeline not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Pipeline not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid pipeline ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded pipeline ID",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "stage_id",
                        "in": "query",
                        "required": false,
                        "description": "Base64 encoded stage ID \u00e2\u20ac\u201d filter contacts by a specific stage (optional)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "assigned_to",
                        "in": "query",
                        "required": false,
                        "description": "Filter by assigned user ID (optional)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (default 15, max 30)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number (default 1)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/pipeline/{id}/stages": {
            "get": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "List Pipeline Stages",
                "description": "Stages for one pipeline, with contact counts and ghl_stage_id when the board is linked to LeadConnector.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Pipeline stages",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "pipeline": {
                                            "id": "MQ==",
                                            "name": "Sales Pipeline"
                                        },
                                        "stages": [
                                            {
                                                "id": "MQ==",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "New Lead",
                                                "sorting_order": 0,
                                                "ghl_stage_id": "e93ba61a-53b3-45e7-985a-c7732dbcdb69",
                                                "contacts_count": 12
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Pipeline not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Pipeline not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded pipeline ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Add Stage to Pipeline",
                "description": "Add a stage. On a linked pipeline the new stage is pushed to LeadConnector.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Stage added successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Stage added successfully.",
                                    "data": {
                                        "id": "OTY=",
                                        "pipeline_id": "MQ==",
                                        "stage_name": "Qualified",
                                        "sorting_order": 3,
                                        "ghl_stage_id": null
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Pipeline not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Pipeline not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "stage_name is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to add stage."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded pipeline ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AddPipelineStageRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/pipeline/stages/reorder": {
            "post": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Reorder Stages",
                "description": "Reorder all stages within a pipeline in one request. Send stages as an ordered array \u00e2\u20ac\u201d the position in the array determines the final sorting_order (first item = 0, second = 1, \u00e2\u20ac\u00a6). Any sorting_order value inside each item is ignored. All stage IDs are validated first \u00e2\u20ac\u201d if any stage is invalid or does not belong to this pipeline, the entire request is rejected and nothing is updated. Only when all stages are valid, all sorting_orders are updated together in a single transaction.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Stages reordered successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Stages reordered successfully.",
                                    "data": {
                                        "pipeline_id": "MQ==",
                                        "stages": [
                                            {
                                                "id": "OTU=",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "Positive",
                                                "sorting_order": 0
                                            },
                                            {
                                                "id": "OTM=",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "New Lead",
                                                "sorting_order": 1
                                            },
                                            {
                                                "id": "OTQ=",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "Negative",
                                                "sorting_order": 2
                                            },
                                            {
                                                "id": "OTY=",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "Qualified",
                                                "sorting_order": 3
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Pipeline or stage not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Stage not found or does not belong to this pipeline."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "pipeline_id is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to reorder stages."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ReorderPipelineStagesRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/pipeline/stages/update/{id}": {
            "put": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Update Stage",
                "description": "Rename a pipeline stage. On a linked pipeline the name is pushed to LeadConnector. To change order, use Reorder Stages.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Stage updated successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Stage updated successfully.",
                                    "data": {
                                        "updated_stage": {
                                            "id": "OTM=",
                                            "pipeline_id": "MQ==",
                                            "stage_name": "Qualified",
                                            "sorting_order": 0,
                                            "created_at": "2025-11-03T10:00:00Z",
                                            "updated_at": "2025-11-04T09:15:00Z"
                                        },
                                        "all_stages": [
                                            {
                                                "id": "OTM=",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "Qualified",
                                                "sorting_order": 0
                                            },
                                            {
                                                "id": "OTQ=",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "New Lead",
                                                "sorting_order": 1
                                            },
                                            {
                                                "id": "OTU=",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "Positive",
                                                "sorting_order": 2
                                            },
                                            {
                                                "id": "OTY=",
                                                "pipeline_id": "MQ==",
                                                "stage_name": "Negative",
                                                "sorting_order": 3
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Stage not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Stage not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "stage_name is required and must not be empty."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update stage."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded stage ID (from Get Pipeline By ID or Get Stage By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdatePipelineStageRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/pipeline/stages/delete/{id}": {
            "delete": {
                "tags": [
                    "Pipeline"
                ],
                "summary": "Delete Stage",
                "description": "Delete a stage and close the sorting_order gap. On a linked pipeline the remaining stages are pushed to LeadConnector. At least one stage should remain on the board.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Stage deleted successfully",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Stage deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Stage not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Stage not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid stage ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete stage."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 encoded stage ID (from Get Pipeline By ID or Get Stage By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/knowledge-hub/courses": {
            "get": {
                "tags": [
                    "Knowledge Hub"
                ],
                "summary": "List Courses",
                "description": "Returns a paginated list of Knowledge Hub courses for the authenticated company (title, description, status, created_at).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated courses",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "title": "Sample Course",
                                                "description": "Course description",
                                                "status": "published",
                                                "created_at": "2025-12-26T06:43:00.000000Z"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 1,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/knowledge-hub/courses/{id}": {
            "get": {
                "tags": [
                    "Knowledge Hub"
                ],
                "summary": "Get Course By ID",
                "description": "Retrieve a single Knowledge Hub course by its ID. The course must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Course details",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "title": "Sample Course",
                                        "description": "Course description",
                                        "thumbnail": null,
                                        "status": "published",
                                        "visibility": "public",
                                        "preview_enabled": false,
                                        "preview_content_limit": 1,
                                        "preview_description": null,
                                        "company_id": 1,
                                        "added_by": 1,
                                        "created_at": "2025-12-26T06:43:00.000000Z",
                                        "updated_at": "2025-12-26T06:43:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Course not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Course not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid course ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Course ID (From List Courses API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/knowledge-hub/available-courses": {
            "get": {
                "tags": [
                    "Knowledge Hub"
                ],
                "summary": "List Available Courses",
                "description": "Returns a paginated list of courses the company can access for joining: the company's own public published courses, Admin-created public courses, and courses assigned to the company. Matches the web \"Available Courses\" behavior.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated available courses",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "title": "Sample Course",
                                                "description": "Course description",
                                                "thumbnail": null,
                                                "status": "published",
                                                "visibility": "public",
                                                "company_id": 1,
                                                "created_at": "2025-12-26T06:43:00.000000Z"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 1,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/knowledge-hub/available-courses/{id}": {
            "get": {
                "tags": [
                    "Knowledge Hub"
                ],
                "summary": "Get Available Course By ID",
                "description": "Retrieve a single courseby ID only if it is available to the authenticated company",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Course details",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "title": "Sample Course",
                                        "description": "Course description",
                                        "thumbnail": null,
                                        "status": "published",
                                        "visibility": "public",
                                        "preview_enabled": false,
                                        "preview_content_limit": 1,
                                        "preview_description": null,
                                        "company_id": 1,
                                        "added_by": 1,
                                        "created_at": "2025-12-26T06:43:00.000000Z",
                                        "updated_at": "2025-12-26T06:43:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Course not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Course not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid course ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Course ID (From List Available Courses API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "List Workflows",
                "description": "Returns a paginated list of workflows for the authenticated company (name, status, created_by, folder_id, timestamps).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated workflows",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "name": "Sample Workflow",
                                                "status": "draft",
                                                "created_by": "Company Dev",
                                                "folder_id": 0,
                                                "created_at": "2026-04-03T12:00:00.000000Z",
                                                "updated_at": "2026-04-03T12:00:00.000000Z"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 1,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "folder_id",
                        "in": "query",
                        "required": false,
                        "description": "Optional folder ID to filter, or omit for all workflows",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/{id}": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Get Workflow By ID",
                "description": "Retrieve a single workflow by its ID. Must belong to the authenticated company. Includes description and trigger_config.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Workflow details",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "company_id": 1,
                                        "added_by": 1,
                                        "name": "Sample Workflow",
                                        "description": "Workflow description",
                                        "status": "draft",
                                        "trigger_config": {
                                            "triggers": [],
                                            "actions": []
                                        },
                                        "folder_id": 0,
                                        "created_by": "Company Dev",
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Workflow not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid workflow ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (from List Workflows API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/create": {
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Create Workflow",
                "description": "Same validation as the web workflow form: name is required; description and trigger_config are optional. New workflows are created in draft status.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Workflow created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "company_id": 1,
                                        "added_by": 1,
                                        "name": "My Workflow",
                                        "description": "Workflow description",
                                        "status": "draft",
                                        "trigger_config": [],
                                        "folder_id": 0,
                                        "created_by": "Company Dev",
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "The name field is required.",
                                    "errors": {
                                        "name": [
                                            "The name field is required."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to create workflow: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateWorkflowRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/update/{id}": {
            "put": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Update Workflow",
                "description": "Update an existing workflow. Same rules as the web workflow form: name and status are required (status: active, inactive, or draft); description and trigger_config are optional. Workflow ID is(from List / Get Workflow APIs).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Workflow updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "company_id": 1,
                                        "added_by": 1,
                                        "name": "My Workflow",
                                        "description": "Workflow description",
                                        "status": "active",
                                        "trigger_config": [],
                                        "folder_id": 0,
                                        "created_by": "Company Dev",
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:05:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Workflow not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID or validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid workflow ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update workflow: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (From List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateWorkflowRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/{id}/status": {
            "put": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Update Workflow Status",
                "description": "Updates only the workflow status. Path id is base64 workflow id.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Status updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Workflow status updated successfully.",
                                    "data": {
                                        "id": "MQ==",
                                        "company_id": 1,
                                        "added_by": 1,
                                        "name": "My Workflow",
                                        "description": "Workflow description",
                                        "status": "active",
                                        "trigger_config": [],
                                        "folder_id": 0,
                                        "created_by": "Company Dev",
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:05:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Workflow not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID or validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid workflow ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update workflow status: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (from List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WorkflowStatusUpdateRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/delete/{id}": {
            "delete": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Delete Workflow",
                "description": "Delete a workflow by ID. Workflow ID is base64 (from List Workflows or Get Workflow By ID API). Must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Workflow deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Workflow deleted successfully!"
                                }
                            }
                        }
                    },
                    {
                        "description": "Workflow not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid workflow ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete workflow: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (From List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/duplicate/{id}": {
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Duplicate Workflow",
                "description": "Clone an existing workflow. Same behavior as the web Duplicate action: the copy is named with a \" (Copy)\" suffix and set to draft status. Source workflow ID (from List Workflows or Get Workflow By ID API).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Workflow duplicated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Workflow duplicated successfully!",
                                    "data": {
                                        "id": "Mg==",
                                        "company_id": 1,
                                        "added_by": 1,
                                        "name": "Sample Workflow (Copy)",
                                        "description": "Workflow description",
                                        "status": "draft",
                                        "trigger_config": [],
                                        "folder_id": 0,
                                        "created_by": "Company Dev",
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Workflow not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid workflow ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to duplicate workflow: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID to duplicate (From List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/folder": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "List Workflow Folders",
                "description": "Returns all workflow folders for the authenticated company, ordered by sort_order then id (same as the web workflow page folder list).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Workflow folders list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "f_name": "Main Workflows",
                                                "parent_id": null,
                                                "sort_order": 0,
                                                "added_by": 1,
                                                "created_at": "2026-04-03T12:00:00.000000Z",
                                                "updated_at": "2026-04-03T12:00:00.000000Z"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/Workflow/folder/create": {
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Create Workflow Folder",
                "description": "Create a new workflow folder for the authenticated company. Same validation as the web form: f_name is required (max 100 characters).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Folder created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Folder created successfully",
                                    "data": {
                                        "id": "MQ==",
                                        "f_name": "My Folder",
                                        "parent_id": null,
                                        "sort_order": 1,
                                        "added_by": 1,
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "The f_name field is required.",
                                    "errors": {
                                        "f_name": [
                                            "The f_name field is required."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to create folder: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateWorkflowFolderRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/folder/update/{id}": {
            "put": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Update Workflow Folder",
                "description": "Rename a workflow folder.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Folder updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Folder updated successfully",
                                    "data": {
                                        "id": "MQ==",
                                        "f_name": "Renamed Folder",
                                        "parent_id": null,
                                        "sort_order": 1,
                                        "added_by": 1,
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:10:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Folder not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Folder not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID or validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid folder ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to update folder: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Folder ID (From List Workflow Folders API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateWorkflowFolderRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/folder/delete/{id}": {
            "delete": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Delete Workflow Folder",
                "description": "Delete a workflow folder. Folder ID (from List Workflow Folders API).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Folder deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Folder deleted successfully"
                                }
                            }
                        }
                    },
                    {
                        "description": "Folder not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Folder not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid folder ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete folder: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Folder ID (From List Workflow Folders API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/folder/reorder": {
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Reorder Workflow Folders",
                "description": "Sets the display order of workflow folders for the authenticated company (same behavior as the web workflow page drag-and-drop). Send every folder id in the desired order; sort_order is set to 1..n.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Folders reordered",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Folders reordered successfully"
                                }
                            }
                        }
                    },
                    {
                        "description": "Folder not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "One or more folders were not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid folder ID at position 1."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to reorder folders: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ReorderWorkflowFoldersRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/folder/move-to-folder/{id}": {
            "put": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Move Workflow To Folder",
                "description": "Assigns the workflow to a folder. Body folder_id must be base64 (from List Workflow Folders), same as list records; use MA== for uncategorized. Path id is the workflow id (base64 from List Workflows or Get Workflow By ID API).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Workflow moved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Workflow moved successfully",
                                    "data": {
                                        "id": "MQ==",
                                        "company_id": 1,
                                        "added_by": 1,
                                        "name": "My Workflow",
                                        "description": "Workflow description",
                                        "status": "active",
                                        "trigger_config": [],
                                        "folder_id": "MQ==",
                                        "created_by": "Company Dev",
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:10:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID or validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid workflow ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to move workflow: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (From List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MoveWorkflowToFolderRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/execution-log": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Execution Log",
                "description": "Paginated workflow execution history for the company. Execution and workflow IDs are base64-encoded. Optional filters match the web Execution Log page.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated execution log",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "workflow_id": "Mg==",
                                                "workflow_name": "Sample Workflow",
                                                "trigger_id": "trig-1",
                                                "trigger_type": "manual",
                                                "trigger_data": null,
                                                "status": "completed",
                                                "contact_id": null,
                                                "current_action_index": 2,
                                                "total_actions": 2,
                                                "started_at": "2026-04-03T12:00:00.000000Z",
                                                "completed_at": "2026-04-03T12:00:05.000000Z",
                                                "duration_seconds": 5,
                                                "error_message": null,
                                                "created_at": "2026-04-03T12:00:00.000000Z",
                                                "updated_at": "2026-04-03T12:00:05.000000Z"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 1,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "workflow_id",
                        "in": "query",
                        "required": false,
                        "description": "Optional \u00e2\u20ac\u201d base64 workflow ID from List Workflows, or All",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "trigger_type",
                        "in": "query",
                        "required": false,
                        "description": "Optional \u00e2\u20ac\u201d trigger type, or All",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Optional \u00e2\u20ac\u201d pending, running, completed, failed, cancelled, paused, or All",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "description": "Optional \u00e2\u20ac\u201d filter created_at from (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "description": "Optional \u00e2\u20ac\u201d filter created_at to (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/execution-log/{id}": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Get Execution Log By ID",
                "description": "Retrieve a single workflow execution by ID. Includes step-by-step execution records. Must belong to the authenticated company.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Execution details",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "MQ==",
                                        "workflow_id": "Mg==",
                                        "workflow_name": "Sample Workflow",
                                        "trigger_id": "trig-1",
                                        "trigger_type": "manual",
                                        "trigger_data": null,
                                        "status": "completed",
                                        "contact_id": null,
                                        "contact_name": null,
                                        "current_action_index": 2,
                                        "total_actions": 2,
                                        "started_at": "2026-04-03T12:00:00.000000Z",
                                        "completed_at": "2026-04-03T12:00:05.000000Z",
                                        "duration_seconds": 5,
                                        "error_message": null,
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:00:05.000000Z",
                                        "steps": [
                                            {
                                                "id": "Mw==",
                                                "action_id": "act-1",
                                                "action_type": "send_sms",
                                                "action_config": [],
                                                "step_order": 1,
                                                "status": "completed",
                                                "started_at": "2026-04-03T12:00:01.000000Z",
                                                "completed_at": "2026-04-03T12:00:02.000000Z",
                                                "duration_ms": 1000,
                                                "request_data": null,
                                                "response_data": null,
                                                "error_message": null,
                                                "retry_count": 0,
                                                "created_at": "2026-04-03T12:00:01.000000Z",
                                                "updated_at": "2026-04-03T12:00:02.000000Z"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Execution not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Execution not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid execution ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Execution ID (from Execution Log list API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Delete Execution Log Entry",
                "description": "Hard-deletes a single execution log entry along with all its associated steps and logs. Any execution status can be deleted (no status restriction). Must belong to the authenticated company. Execution ID is base64 (same as Execution Log list API). Path: /api/Workflow/execution-log/{id}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Execution log deleted successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Execution not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid execution ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to delete execution log: \u2026"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Execution ID (base64, from Execution Log list API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/execution-log/{id}/retry": {
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Retry Failed Execution",
                "description": "Retry a failed or cancelled execution. Dispatches a fresh ProcessWorkflowJob using the original trigger_type and trigger_data from the failed execution \u2014 the same execution engine as all other triggers. Original execution record stays intact (still failed/cancelled); a brand-new execution record is created by the executor. Workflow must be active. Execution ID is base64 (same as Execution Log list API). Path: /api/Workflow/execution-log/{id}/retry.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Retry queued",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Execution retry queued successfully.",
                                    "data": {
                                        "original_execution_id": "MQ==",
                                        "workflow_id": "Mg==",
                                        "workflow_name": "My Workflow",
                                        "trigger_type": "manual_enrollment",
                                        "contact_id": 101
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Execution not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not retryable / workflow inactive",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Only failed or cancelled executions can be retried."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to retry execution: \u2026"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Execution ID (base64, from Execution Log list API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/execution-log/{id}/cancel": {
            "put": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Cancel Running Execution",
                "description": "Cancel a running, pending, or paused execution. Marks status as cancelled and sets completed_at to now. Safe for paused executions \u2014 any queued ResumeWorkflowJob will skip silently (executor guards against non-paused status). Already completed, failed, or cancelled executions return 422. Execution ID is base64 (same as Execution Log list API). Path: /api/Workflow/execution-log/{id}/cancel.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Execution cancelled",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Execution cancelled successfully.",
                                    "data": {
                                        "execution_id": "MQ==",
                                        "workflow_id": "Mg==",
                                        "workflow_name": "My Workflow",
                                        "contact_id": 101,
                                        "status": "cancelled",
                                        "completed_at": "2026-04-28T22:00:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Execution not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not cancellable",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Only running, pending, or paused executions can be cancelled."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to cancel execution: \u2026"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Execution ID (base64, from Execution Log list API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/builder/helpers/meta-conversions": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder (saved Pixels)",
                "description": "Pixels saved under Marketing \u2192 Meta Ads \u2192 Conversions. Use the id as send_meta_conversion.conversion_id. Token is never returned. Path: /api/Workflow/builder/helpers/meta-conversions.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved Pixels",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": [
                                        {
                                            "id": 3,
                                            "name": "Main Pixel",
                                            "pixel_id": "123456789012345",
                                            "ready": true,
                                            "token_set": true
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            },
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder (save a Pixel)",
                "description": "Create a labeled Pixel from the workflow action so send_meta_conversion can pick it. Same fields as POST /api/marketing/meta-ads/conversions. Token is never returned.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": 3,
                                        "name": "Main Pixel",
                                        "pixel_id": "123456789012345",
                                        "ready": true,
                                        "token_set": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "The name field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsConversionSettingsRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/builder/helpers/contact-fields": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder (contact merge fields)",
                "description": "Company contact columns for message merge fields (custom fields included). Each item: key, label, placeholder ({{contact.field}}), default_value (empty if none), group=contact|custom. Path: /api/Workflow/builder/helpers/contact-fields.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact fields",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "table": "contacts_1",
                                        "fields": [
                                            {
                                                "key": "first_name",
                                                "label": "First Name",
                                                "placeholder": "{{contact.first_name}}",
                                                "default_value": "Dev",
                                                "group": "contact"
                                            },
                                            {
                                                "key": "custom_field_1",
                                                "label": "Custom Field 1",
                                                "placeholder": "{{contact.custom_field_1}}",
                                                "default_value": "",
                                                "group": "custom"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "\u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/Workflow/builder/{id}": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder (load graph)",
                "description": "Returns everything needed to open the workflow editor: graph, settings, live trigger/action catalog (including appointment_status and openai_gpt with config_fields/filters), trigger_types map from the catalog, openai_configured (true when Settings > Integration > OpenAI is connected), allowed_*_types, company users, timezones, GHL locations. Workflow ID is base64. Path: /api/Workflow/builder/{id}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Builder payload",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "Mg==",
                                        "company_id": 1,
                                        "added_by": 1,
                                        "name": "Sample Workflow",
                                        "description": "Workflow description",
                                        "status": "draft",
                                        "trigger_config": {
                                            "triggers": [],
                                            "actions": []
                                        },
                                        "folder_id": null,
                                        "created_by": "Admin",
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:00:00.000000Z",
                                        "settings": null,
                                        "triggers": [],
                                        "actions": [],
                                        "trigger_types": {
                                            "contact_created": "Contact Created",
                                            "contact_changed": "Contact Changed",
                                            "appointment_status": "Appointment Status"
                                        },
                                        "openai_configured": true,
                                        "company_users": [],
                                        "timezones": [],
                                        "ghl_locations": [
                                            {
                                                "id": 1,
                                                "locationId": "loc_xxx",
                                                "location_name": "Main Location",
                                                "companyId": "cmp_yyy"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Workflow not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid workflow ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (from List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder (save graph)",
                "description": "Save the full workflow graph. The request body must contain a single key: trigger_config (required). This API only saves the graph \u2014 it does NOT change name, description, or status (use PUT /api/Workflow/update/{id} for those).\n\nHOW TO USE:\n1. Call GET /api/Workflow/builder/{id} to load the existing graph and catalog.\n2. Get valid trigger type values from data.triggers[].type (e.g. appointment_status, contact_changed, contact_created) and action type values from data.actions[].type (e.g. openai_gpt, if_else, send_sms). Using wrong types will save but the web builder UI may not render correctly.\n3. Build your trigger_config with four keys: triggers, actions, nodes, edges, then send via this PUT.\n\nFIELD GUIDE inside trigger_config:\n\u2022 triggers[]: id (unique string), type (from catalog), name (display label), filters (see below).\n\u2022 actions[]: id (unique string), type (from catalog), name (display label), config (fields depend on action type e.g. send_sms uses { message: 'Hi {{contact.first_name}}' }; openai_gpt / GPT / Claude uses { prompt, provider?: openai|claude, model?, action_type? }).\n\u2022 nodes[]: Visual canvas nodes. Each: id, type (trigger or action), position ({x,y}), data ({ label, triggerId or actionId }).\n\u2022 edges[]: Connections between nodes. Each: id, source (node id), target (node id), sourceHandle (null), targetHandle (null).\n\nFILTERS (triggers[].filters):\n\u2022 Send filters: [] to fire with no extra conditions.\n\u2022 Shape: { field, operator, value } and optional to_value for has_changed_to.\n\u2022 appointment_status: event_type (normal|recurring), booking_status (pending=New, confirmed, cancelled, completed=Showed, no_show=No-show, rejected=Invalid), actor_type (api|customer|user|workflow), tags (operator has, contact tag id), calendar_id.\n\u2022 contact_changed: tags (added|removed + tag id), custom_field / changed_fields (is_updated|has_changed_to; has_changed_to needs to_value).\n\u2022 If/Else GPT / Claude: after an openai_gpt action, condition field gpt:<that action id> or gpt. Operators: equals, contains, not_contains, is_empty, is_not_empty.\n\u2022 GET /api/Workflow/builder/helpers/contact-fields returns group=contact|custom for field pickers.\n\u2022 GPT / Claude action requires data.openai_configured or data.claude_configured true.\n\nPath id is the base64-encoded workflow id (from List Workflows or Get Workflow By ID API).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Workflow updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "Mg==",
                                        "company_id": 1,
                                        "added_by": 1,
                                        "name": "Sample Workflow",
                                        "description": "Workflow description",
                                        "status": "draft",
                                        "trigger_config": {
                                            "triggers": [
                                                {
                                                    "id": "trigger-node-1",
                                                    "type": "appointment_status",
                                                    "name": "Appointment Status",
                                                    "filters": [
                                                        {
                                                            "field": "booking_status",
                                                            "operator": "equals",
                                                            "value": "no_show"
                                                        }
                                                    ]
                                                }
                                            ],
                                            "actions": [
                                                {
                                                    "id": "action-1",
                                                    "type": "openai_gpt",
                                                    "name": "GPT / Claude",
                                                    "config": {
                                                        "prompt": "Summarize this contact.",
                                                        "model": "gpt-4o-mini"
                                                    }
                                                }
                                            ],
                                            "nodes": [
                                                {
                                                    "id": "node-trigger-1",
                                                    "type": "trigger",
                                                    "position": {
                                                        "x": 120,
                                                        "y": 80
                                                    },
                                                    "data": {
                                                        "label": "New contact"
                                                    }
                                                },
                                                {
                                                    "id": "node-action-1",
                                                    "type": "action",
                                                    "position": {
                                                        "x": 120,
                                                        "y": 220
                                                    },
                                                    "data": {
                                                        "label": "Send SMS"
                                                    }
                                                }
                                            ],
                                            "edges": [
                                                {
                                                    "id": "edge-1",
                                                    "source": "node-trigger-1",
                                                    "target": "node-action-1"
                                                }
                                            ]
                                        },
                                        "folder_id": null,
                                        "created_by": "Admin",
                                        "created_at": "2026-04-03T12:00:00.000000Z",
                                        "updated_at": "2026-04-03T12:05:00.000000Z"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Workflow not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "trigger_config is required in the JSON body."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to save workflow builder: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (from List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SaveWorkflowBuilderGraphRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/builder/{id}/settings": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder (settings only)",
                "description": "Returns workflow settings only (timezone window, from name/email/number, allowed users) \u00e2\u20ac\u201d same JSON as GET /api/Workflow/builder/{id} under data.settings. Does not load trigger_config, catalogs, or helper lists. Workflow ID is base64. Path: /api/Workflow/builder/{id}/settings.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Workflow settings",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "id": "Mg==",
                                        "settings": {
                                            "id": 1,
                                            "workflow_id": 2,
                                            "timezone": {
                                                "name": "America/Chicago"
                                            },
                                            "time_window_enabled": true,
                                            "start_time": "09:00",
                                            "end_time": "17:00",
                                            "include_days": [
                                                "mon",
                                                "tue",
                                                "wed",
                                                "thu",
                                                "fri"
                                            ],
                                            "from_name": "Support",
                                            "from_email": "support@example.com",
                                            "from_number": "+15551234567",
                                            "allowed_users": [
                                                1,
                                                2
                                            ],
                                            "created_at": "2026-04-03T12:00:00.000000Z",
                                            "updated_at": "2026-04-03T12:00:00.000000Z"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Workflow not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid workflow ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (from List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder (update settings)",
                "description": "Creates or updates workflow_settings for this workflow (same behavior as the web builder save). Path id is base64 workflow id. Response data.settings matches GET on the same path.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Settings saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Settings saved successfully.",
                                    "data": {
                                        "id": "Mg==",
                                        "settings": {
                                            "id": 1,
                                            "workflow_id": 2,
                                            "timezone": {
                                                "name": "America/Chicago"
                                            },
                                            "time_window_enabled": true,
                                            "start_time": "09:00",
                                            "end_time": "17:00",
                                            "include_days": [
                                                "mon",
                                                "tue",
                                                "wed",
                                                "thu",
                                                "fri"
                                            ],
                                            "from_name": "Support",
                                            "from_email": "support@example.com",
                                            "from_number": "+15551234567",
                                            "allowed_users": [
                                                1,
                                                2
                                            ],
                                            "created_at": "2026-04-03T12:00:00.000000Z",
                                            "updated_at": "2026-04-03T12:00:00.000000Z"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Workflow not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The timezone id field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Error saving settings: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (from List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WorkflowSettingsUpdateRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/{id}/contacts": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Enrolled Contacts",
                "description": "Paginated list of contacts currently enrolled in a workflow (executions with status running / pending / paused). Workflow ID is base64 (from List Workflows or Get Workflow By ID API). Use the optional status query param to filter by a specific execution status. Path: /api/Workflow/{id}/contacts.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Enrolled contacts",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "workflow_id": "Mg==",
                                        "workflow_name": "My Workflow",
                                        "records": [
                                            {
                                                "execution_id": "MQ==",
                                                "contact_id": 101,
                                                "contact_name": "John Doe",
                                                "contact_phone": "+15551234567",
                                                "contact_email": "john@example.com",
                                                "execution_status": "running",
                                                "current_action_index": 2,
                                                "total_actions": 5,
                                                "started_at": "2026-04-28T10:00:00.000000Z",
                                                "created_at": "2026-04-28T10:00:00.000000Z"
                                            }
                                        ],
                                        "pagination": {
                                            "total": 1,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1,
                                            "from": 1,
                                            "to": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Workflow not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid workflow ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (base64, from List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Results per page (default 15, max 30)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filter by execution status (running, pending, paused, completed, failed). Leave blank for all active (running/pending/paused).",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/{id}/contacts/enroll": {
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Enroll Contact into Workflow",
                "description": "Manually enroll a contact into a workflow. Dispatches a background job (ProcessWorkflowJob) with trigger_type = manual_enrollment \u00e2\u20ac\u201d same execution engine as all other triggers. Workflow must be active. contact_id must exist in the company contacts table. Re-enrollment is allowed (no duplicate check); a new execution record is created each time. Path: /api/Workflow/{id}/contacts/enroll.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact enrolled",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Contact enrollment queued successfully.",
                                    "data": {
                                        "workflow_id": "Mg==",
                                        "workflow_name": "My Workflow",
                                        "contact_id": "MTAx",
                                        "contact_name": "John Doe",
                                        "trigger_type": "manual_enrollment"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation / inactive workflow",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Only active workflows can enroll contacts."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to enroll contact: \u00e2\u20ac\u00a6"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (base64, from List Workflows or Get Workflow By ID API). Workflow must be active.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WorkflowEnrollContactRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/{id}/test-run": {
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Test Run Workflow",
                "description": "Trigger a test execution of the workflow for a given contact. Works on any workflow status (draft, inactive, active) \u2014 bypasses the active check so you can test before publishing. Dispatches ProcessWorkflowJob with trigger_type = test_run and is_test = true in trigger_data, so test executions are clearly labelled in the execution log. contact_id must exist in the company contacts table. Waits are skipped in test runs. Optional test_reply (text) makes a \"Wait for reply\" step take its Replied path with that text (omit for No reply); optional test_business_hours (open|closed) forces the If/Else business_hours condition (omit for the real hours now). Path: /api/Workflow/{id}/test-run.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Test queued",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Test execution queued successfully.",
                                    "data": {
                                        "workflow_id": "Mg==",
                                        "workflow_name": "My Workflow",
                                        "workflow_status": "draft",
                                        "contact_id": "MTAx",
                                        "contact_name": "John Doe",
                                        "trigger_type": "test_run"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The contact id field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Server error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Failed to queue test execution: \u2026"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (base64). Works on draft, inactive, and active workflows.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WorkflowEnrollContactRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/{id}/contacts/{contact_id}": {
            "delete": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Unenroll Contact from Workflow",
                "description": "Cancels all active executions (status: running / pending / paused) for this contact in the workflow. Marks them as cancelled with completed_at timestamp. Any queued ResumeWorkflowJobs for paused executions will skip silently (executor guards against non-paused status). Returns 404 if no active enrollment exists. Both id and contact_id are base64-encoded. Path: /api/Workflow/{id}/contacts/{contact_id}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Contact unenrolled",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Contact unenrolled successfully.",
                                    "data": {
                                        "workflow_id": "Mg==",
                                        "workflow_name": "My Workflow",
                                        "contact_id": "MTAx",
                                        "contact_name": "John Doe",
                                        "executions_cancelled": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "No active enrollment found for this contact in the workflow."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid ID",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid contact_id. Must be a base64-encoded contact ID."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (base64, from List Workflows or Get Workflow By ID API)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "contact_id",
                        "in": "path",
                        "required": true,
                        "description": "Contact ID (base64-encoded \u2014 e.g. contact id 101 \u2192 base64_encode(\"101\") = \"MTAx\")",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/catalog/triggers": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "List Trigger Catalog",
                "description": "Returns all active workflow trigger types from the global catalog \u2014 same source as the workflow builder trigger picker. config_fields includes live filter schemas for newer types (appointment_status, contact_changed) even if seeders have not been re-run. Path: /api/Workflow/catalog/triggers.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Trigger catalog",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "total": 2,
                                        "categories": [
                                            "Contacts",
                                            "Appointments"
                                        ],
                                        "triggers": [
                                            {
                                                "id": 1,
                                                "name": "Contact Created",
                                                "type": "contact_created",
                                                "category": "Contacts",
                                                "icon": "ri-user-add-line",
                                                "color": "text-success",
                                                "description": "Triggers when a new contact is created",
                                                "config_fields": [],
                                                "sort_order": 2
                                            },
                                            {
                                                "id": 10,
                                                "name": "Appointment Status",
                                                "type": "appointment_status",
                                                "category": "Appointments",
                                                "icon": "ri-calendar-event-line",
                                                "color": "text-primary",
                                                "description": "Triggers when appointment status changes",
                                                "config_fields": {
                                                    "filters": [
                                                        {
                                                            "field": "booking_status",
                                                            "label": "Booking Status",
                                                            "type": "select",
                                                            "options": [
                                                                "pending",
                                                                "confirmed",
                                                                "cancelled",
                                                                "completed",
                                                                "no_show",
                                                                "rejected"
                                                            ]
                                                        },
                                                        {
                                                            "field": "event_type",
                                                            "label": "Event Type",
                                                            "type": "select",
                                                            "options": [
                                                                "normal",
                                                                "recurring"
                                                            ]
                                                        }
                                                    ]
                                                },
                                                "sort_order": 10
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "description": "Filter by category name (e.g. Contacts, Appointments). Leave blank to return all.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/catalog/actions": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "List Action Catalog",
                "description": "Returns all active workflow action types from the global catalog \u2014 same source as the workflow builder action picker. Each action has: id, name, type (machine key used in trigger_config actions array), category, icon, color, description, config_fields (array of configurable fields for that action), sort_order. Also returns a distinct list of categories. Use the optional ?category= query param to filter by a single category. Path: /api/Workflow/catalog/actions.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Action catalog",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "total": 16,
                                        "categories": [
                                            "AI",
                                            "Communication",
                                            "Contact",
                                            "Integration",
                                            "Internal",
                                            "Notification",
                                            "Pipeline"
                                        ],
                                        "actions": [
                                            {
                                                "id": 1,
                                                "name": "Add Contact Tag",
                                                "type": "add_contact_tag",
                                                "category": "Contact",
                                                "icon": "ri-price-tag-3-line",
                                                "color": "text-primary",
                                                "description": "Add tags to contact in GoHighLevel",
                                                "config_fields": null,
                                                "sort_order": 1
                                            },
                                            {
                                                "id": 9,
                                                "name": "If / Else",
                                                "type": "if_else",
                                                "category": "Logic",
                                                "icon": "ri-git-branch-line",
                                                "color": "text-warning",
                                                "description": "Branch on a contact field or GPT / Claude response (field gpt:<openai_gpt node id>)",
                                                "config_fields": {
                                                    "gpt_field": "Use condition field gpt:<openai_gpt node id> or gpt"
                                                },
                                                "sort_order": 12
                                            },
                                            {
                                                "id": 0,
                                                "name": "Wait for reply",
                                                "type": "wait_for_reply",
                                                "category": "Flow Control",
                                                "icon": "ri-chat-history-line",
                                                "color": "text-secondary",
                                                "description": "Pause until the contact replies (text, iMessage, email or call) or a timeout passes, then go down Replied or No reply. The reply is {{reply.text}} / If/Else last_reply.",
                                                "config_fields": {
                                                    "timeout_value": {
                                                        "type": "integer",
                                                        "required": true
                                                    },
                                                    "timeout_unit": {
                                                        "type": "select",
                                                        "options": [
                                                            "minutes",
                                                            "hours",
                                                            "days"
                                                        ],
                                                        "required": true
                                                    },
                                                    "branches": "Edge sourceHandle \"replied\" or \"no_reply\"."
                                                },
                                                "sort_order": 18
                                            },
                                            {
                                                "id": 16,
                                                "name": "GPT / Claude",
                                                "type": "openai_gpt",
                                                "category": "AI",
                                                "icon": "ri-sparkling-2-line",
                                                "color": "text-info",
                                                "description": "Run an OpenAI or Claude prompt and store the response",
                                                "config_fields": {
                                                    "prompt": {
                                                        "type": "text",
                                                        "required": true
                                                    },
                                                    "model": {
                                                        "type": "select",
                                                        "options": [
                                                            "gpt-4o-mini",
                                                            "gpt-4o"
                                                        ]
                                                    }
                                                },
                                                "sort_order": 16
                                            },
                                            {
                                                "id": 10,
                                                "name": "Send SMS",
                                                "type": "send_sms",
                                                "category": "Communication",
                                                "icon": "ri-message-2-line",
                                                "color": "text-success",
                                                "description": "Send SMS message to contact",
                                                "config_fields": null,
                                                "sort_order": 7
                                            },
                                            {
                                                "id": 21,
                                                "name": "Meta Conversion API",
                                                "type": "send_meta_conversion",
                                                "category": "Integration",
                                                "icon": "ri-facebook-circle-line",
                                                "color": "text-info",
                                                "description": "Send a Lead, Schedule, Purchase or custom stage event to a saved Pixel",
                                                "config_fields": {
                                                    "conversion_id": {
                                                        "type": "integer",
                                                        "required": true
                                                    },
                                                    "event_name": {
                                                        "type": "select",
                                                        "options": [
                                                            "Lead",
                                                            "Schedule",
                                                            "Purchase",
                                                            "Custom"
                                                        ],
                                                        "default": "Lead"
                                                    },
                                                    "custom_event_name": {
                                                        "type": "string"
                                                    },
                                                    "value": {
                                                        "type": "string",
                                                        "description": "Required for Purchase. Number or {{contact.deal_value}}."
                                                    },
                                                    "currency": {
                                                        "type": "string",
                                                        "default": "USD"
                                                    }
                                                },
                                                "sort_order": 21
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "description": "Filter by category name (e.g. Internal, Communication, Contact, AI, Integration, Notification, Pipeline). Leave blank to return all.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/builder/rules": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder rules + catalog",
                "description": "Graph rules plus live allowed trigger/action types and catalog rows (config_fields includes appointment_status filters, openai_gpt, If/Else GPT, send_meta_conversion). Path: /api/Workflow/builder/rules.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Builder rules",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "allowed_trigger_types": [
                                            "appointment_status",
                                            "contact_changed",
                                            "contact_created"
                                        ],
                                        "allowed_action_types": [
                                            "openai_gpt",
                                            "if_else",
                                            "send_sms",
                                            "send_meta_conversion",
                                            "add_to_powerlist"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/Workflow/builder/{id}/test": {
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder test fire",
                "description": "Test-run a specific trigger (including appointment_status) on draft or active workflows. Provide contact_id or phone. Path: /api/Workflow/builder/{id}/test.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Test fired",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Test execution queued."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Provide either contact_id or phone for the test contact."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (base64)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WorkflowBuilderTestRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/Workflow/builder/{id}/business-hours": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow business hours",
                "description": "The hours this workflow's business-hours steps use right now (If/Else condition business_hours, Wait mode until_business_hours): source working_hours (Settings \u2192 Working Hours, company time zone), workflow_window (this workflow's Time window, when no Working Hours are set) or default (Mon-Fri 9:00-17:00 in the workflow time zone). Path: /api/Workflow/builder/{id}/business-hours.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Business hours",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "source": "working_hours",
                                        "timezone": "America/Chicago",
                                        "label": "Mon\u2013Fri 9:00 AM\u20135:00 PM (CDT)",
                                        "note": "From Settings \u2192 Working Hours.",
                                        "is_open_now": false,
                                        "next_open_at": "2026-10-19T14:00:00+00:00"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Workflow not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (base64)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/builder/{id}/executions": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder executions (History tab)",
                "description": "Recent executions for the builder History tab. Path: /api/Workflow/builder/{id}/executions.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Executions list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (base64)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/builder/{id}/executions/{executionId}": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Workflow Builder execution detail",
                "description": "Single execution with steps. Path: /api/Workflow/builder/{id}/executions/{executionId}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Execution detail",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (base64)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "executionId",
                        "in": "path",
                        "required": true,
                        "description": "Numeric execution id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/builder/{id}/enrollment-history": {
            "get": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Enrollment History",
                "description": "Enrollment History tab: who entered this workflow, trigger type (including appointment_status / scheduled_enrollment / openai_gpt runs), current action, status. Path: /api/Workflow/builder/{id}/enrollment-history.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Enrollment history",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "retention_days": 30,
                                    "event_options": [
                                        {
                                            "value": "appointment_status",
                                            "label": "Appointment Status"
                                        }
                                    ],
                                    "data": {
                                        "workflow_id": "Mg==",
                                        "workflow_name": "No-show follow-up",
                                        "records": [
                                            {
                                                "id": 55,
                                                "contact": {
                                                    "id": 101,
                                                    "name": "John Doe",
                                                    "phone": "+15551234567"
                                                },
                                                "trigger_type": "appointment_status",
                                                "current_status": "running",
                                                "can_remove": true
                                            }
                                        ],
                                        "pagination": {
                                            "total": 1,
                                            "current_page": 1,
                                            "per_page": 15,
                                            "last_page": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (base64)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Rows per page",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "event",
                        "in": "query",
                        "required": false,
                        "description": "Trigger type filter, e.g. appointment_status",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/builder/{id}/enrollments/{executionId}/remove": {
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Remove enrollment",
                "description": "Cancel one running/pending/paused enrollment from Enrollment History. Path: /api/Workflow/builder/{id}/enrollments/{executionId}/remove.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Removed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Enrollment removed."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not active",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Only active enrollments can be removed."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Workflow ID (base64)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "executionId",
                        "in": "path",
                        "required": true,
                        "description": "Execution id from enrollment history",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/Workflow/builder/agent/chat": {
            "post": {
                "tags": [
                    "Workflow"
                ],
                "summary": "Build with AI (in-app)",
                "description": "In-app workflow AI builder. Prompt includes appointment_status, openai_gpt, and If/Else GPT filters. Not the remote MCP server. Path: /api/Workflow/builder/agent/chat.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Graph suggestion",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "trigger_config": []
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "message": {
                                        "type": "string",
                                        "example": "When appointment is no-show, run GPT then SMS"
                                    },
                                    "workflow_id": {
                                        "type": "string"
                                    },
                                    "current_graph": {
                                        "type": "object"
                                    }
                                },
                                "required": [
                                    "message"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/settings/openai": {
            "get": {
                "tags": [
                    "Settings"
                ],
                "summary": "OpenAI status",
                "description": "Company OpenAI connection used by the GPT / Claude (openai_gpt) workflow action. Never returns the API key. Path: /api/settings/openai.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Status",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "enabled": true,
                                        "api_key_set": true,
                                        "connected": true,
                                        "configured": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            },
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Save OpenAI key",
                "description": "Enable/save the company OpenAI key for GPT / Claude workflow actions. Path: /api/settings/openai.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "OpenAI connection saved successfully.",
                                    "data": {
                                        "enabled": true,
                                        "api_key_set": true,
                                        "configured": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OpenAiSettingsUpdateRequest"
                            }
                        }
                    }
                }
            },
            "put": {
                "tags": [
                    "Settings"
                ],
                "summary": "Save OpenAI key (PUT)",
                "description": "Same as POST /api/settings/openai.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OpenAiSettingsUpdateRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/settings/openai/test": {
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Test OpenAI key",
                "description": "Validates the company OpenAI key (or a key in the body) without storing a new one unless you also save. Path: /api/settings/openai/test.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "OpenAI connected successfully."
                                }
                            }
                        }
                    },
                    {
                        "description": "Rejected",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "You exceeded your current quota."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/settings/openai/disconnect": {
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Disconnect OpenAI",
                "description": "Clears the company OpenAI key. GPT / Claude actions that use OpenAI will fail until reconnected. Path: /api/settings/openai/disconnect.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Disconnected",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/settings/resend": {
            "get": {
                "tags": [
                    "Settings"
                ],
                "summary": "Resend status",
                "description": "The company's own Resend connection: domains with their Resend status, the chosen sending domain, receiving (Inbox) setup and a plain next_step. `status`: not_connected | choose_domain | active | error. Never returns the API key (only key_last4) or the signing secret. Path: /api/settings/resend.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Status",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "connected": true,
                                        "status": "active",
                                        "active": true,
                                        "key_last4": "a1B2",
                                        "domains": [
                                            {
                                                "name": "harbordental.com",
                                                "status": "verified",
                                                "region": "us-east-1",
                                                "receiving": "disabled",
                                                "selectable": true,
                                                "records": [
                                                    {
                                                        "purpose": "DKIM",
                                                        "type": "TXT",
                                                        "name": "resend._domainkey",
                                                        "value": "p=MIGfMA0GCSq...",
                                                        "priority": null,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "MX",
                                                        "name": "send",
                                                        "value": "feedback-smtp.us-east-1.amazonses.com",
                                                        "priority": 10,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "TXT",
                                                        "name": "send",
                                                        "value": "v=spf1 include:amazonses.com ~all",
                                                        "priority": null,
                                                        "status": "verified"
                                                    }
                                                ]
                                            }
                                        ],
                                        "domain": "harbordental.com",
                                        "domain_status": "verified",
                                        "domain_region": "us-east-1",
                                        "from_address": "hello@harbordental.com",
                                        "from_name": "Harbor Dental",
                                        "team_senders": [
                                            {
                                                "user_id": 12,
                                                "name": "Eric Smith",
                                                "from": "eric@harbordental.com"
                                            },
                                            {
                                                "user_id": 15,
                                                "name": "Saad Khan",
                                                "from": "saad@harbordental.com"
                                            }
                                        ],
                                        "last_checked_at": "2026-10-18 09:00:00",
                                        "last_test_at": null,
                                        "last_error": null,
                                        "inbound": {
                                            "webhook_url": "https://app.example.com/webhooks/email/resend/AbC123",
                                            "webhook_created_for_you": true,
                                            "signing_secret_set": true,
                                            "address": "replies@abc123.resend.app",
                                            "suggested_address": null,
                                            "reply_address_example": "replies+c1234.1a2b3c4d5e6f@abc123.resend.app",
                                            "replies_come_back": true,
                                            "last_received_at": null
                                        },
                                        "next_step": "Sending from harbordental.com; replies land in the Inbox on the lead's conversation."
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not the account owner",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Only the account owner can connect Resend."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            },
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Connect Resend",
                "description": "Validates a Resend API key (Full access) by listing the account's domains, then saves it encrypted. A key Resend refuses is not saved (422 with a plain reason). Next: choose a verified domain. Path: /api/settings/resend.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Connected",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "connected": true,
                                        "status": "active",
                                        "active": true,
                                        "key_last4": "a1B2",
                                        "domains": [
                                            {
                                                "name": "harbordental.com",
                                                "status": "verified",
                                                "region": "us-east-1",
                                                "receiving": "disabled",
                                                "selectable": true,
                                                "records": [
                                                    {
                                                        "purpose": "DKIM",
                                                        "type": "TXT",
                                                        "name": "resend._domainkey",
                                                        "value": "p=MIGfMA0GCSq...",
                                                        "priority": null,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "MX",
                                                        "name": "send",
                                                        "value": "feedback-smtp.us-east-1.amazonses.com",
                                                        "priority": 10,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "TXT",
                                                        "name": "send",
                                                        "value": "v=spf1 include:amazonses.com ~all",
                                                        "priority": null,
                                                        "status": "verified"
                                                    }
                                                ]
                                            }
                                        ],
                                        "domain": "harbordental.com",
                                        "domain_status": "verified",
                                        "domain_region": "us-east-1",
                                        "from_address": "hello@harbordental.com",
                                        "from_name": "Harbor Dental",
                                        "team_senders": [
                                            {
                                                "user_id": 12,
                                                "name": "Eric Smith",
                                                "from": "eric@harbordental.com"
                                            },
                                            {
                                                "user_id": 15,
                                                "name": "Saad Khan",
                                                "from": "saad@harbordental.com"
                                            }
                                        ],
                                        "last_checked_at": "2026-10-18 09:00:00",
                                        "last_test_at": null,
                                        "last_error": null,
                                        "inbound": {
                                            "webhook_url": "https://app.example.com/webhooks/email/resend/AbC123",
                                            "webhook_created_for_you": true,
                                            "signing_secret_set": true,
                                            "address": "replies@abc123.resend.app",
                                            "suggested_address": null,
                                            "reply_address_example": "replies+c1234.1a2b3c4d5e6f@abc123.resend.app",
                                            "replies_come_back": true,
                                            "last_received_at": null
                                        },
                                        "next_step": "Sending from harbordental.com; replies land in the Inbox on the lead's conversation."
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Key refused",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Resend didn't accept that API key. Copy it again from Resend \u2192 API Keys."
                                }
                            }
                        }
                    },
                    {
                        "description": "Resend unreachable",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Couldn't reach Resend. Try again in a minute."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "api_key": {
                                        "type": "string",
                                        "example": "re_xxxxxxxx",
                                        "description": "Resend API key with Full access"
                                    }
                                },
                                "required": [
                                    "api_key"
                                ]
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Settings"
                ],
                "summary": "Disconnect Resend",
                "description": "Removes the key and stops sending/receiving through Resend. Email goes back to how it was sent before. Path: /api/settings/resend.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Disconnected",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "connected": false,
                                        "status": "not_connected"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/settings/resend/domain": {
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Choose Resend sending domain",
                "description": "Picks the domain lead email is sent from. Only a domain Resend reports as `verified` right now is accepted. from_local is the address for reps whose login is not on the domain (default hello). Path: /api/settings/resend/domain.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "connected": true,
                                        "status": "active",
                                        "active": true,
                                        "key_last4": "a1B2",
                                        "domains": [
                                            {
                                                "name": "harbordental.com",
                                                "status": "verified",
                                                "region": "us-east-1",
                                                "receiving": "disabled",
                                                "selectable": true,
                                                "records": [
                                                    {
                                                        "purpose": "DKIM",
                                                        "type": "TXT",
                                                        "name": "resend._domainkey",
                                                        "value": "p=MIGfMA0GCSq...",
                                                        "priority": null,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "MX",
                                                        "name": "send",
                                                        "value": "feedback-smtp.us-east-1.amazonses.com",
                                                        "priority": 10,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "TXT",
                                                        "name": "send",
                                                        "value": "v=spf1 include:amazonses.com ~all",
                                                        "priority": null,
                                                        "status": "verified"
                                                    }
                                                ]
                                            }
                                        ],
                                        "domain": "harbordental.com",
                                        "domain_status": "verified",
                                        "domain_region": "us-east-1",
                                        "from_address": "hello@harbordental.com",
                                        "from_name": "Harbor Dental",
                                        "team_senders": [
                                            {
                                                "user_id": 12,
                                                "name": "Eric Smith",
                                                "from": "eric@harbordental.com"
                                            },
                                            {
                                                "user_id": 15,
                                                "name": "Saad Khan",
                                                "from": "saad@harbordental.com"
                                            }
                                        ],
                                        "last_checked_at": "2026-10-18 09:00:00",
                                        "last_test_at": null,
                                        "last_error": null,
                                        "inbound": {
                                            "webhook_url": "https://app.example.com/webhooks/email/resend/AbC123",
                                            "webhook_created_for_you": true,
                                            "signing_secret_set": true,
                                            "address": "replies@abc123.resend.app",
                                            "suggested_address": null,
                                            "reply_address_example": "replies+c1234.1a2b3c4d5e6f@abc123.resend.app",
                                            "replies_come_back": true,
                                            "last_received_at": null
                                        },
                                        "next_step": "Sending from harbordental.com; replies land in the Inbox on the lead's conversation."
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not verified / not in the account",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "harbordental.com isn't verified in Resend yet (status: pending). Finish it in Resend \u2192 Domains, then try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "domain": {
                                        "type": "string",
                                        "example": "harbordental.com"
                                    },
                                    "from_local": {
                                        "type": "string",
                                        "example": "hello"
                                    },
                                    "from_name": {
                                        "type": "string",
                                        "example": "Harbor Dental"
                                    }
                                },
                                "required": [
                                    "domain"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/settings/resend/domains": {
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Add a domain to Resend",
                "description": "Adds a domain to the company's own Resend account and returns its DNS records in data.domains[].records (type, name, value, priority) for the owner to add at their DNS host. With no sending domain chosen yet it becomes the sending domain and starts sending by itself once Resend verifies it (call Re-check after adding the records). receiving=true is for a reply subdomain only (reply.theirdomain.com): an MX on the main domain would stop their normal email. Free email domains are refused. Path: /api/settings/resend/domains.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Added",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "connected": true,
                                        "status": "active",
                                        "active": true,
                                        "key_last4": "a1B2",
                                        "domains": [
                                            {
                                                "name": "harbordental.com",
                                                "status": "verified",
                                                "region": "us-east-1",
                                                "receiving": "disabled",
                                                "selectable": true,
                                                "records": [
                                                    {
                                                        "purpose": "DKIM",
                                                        "type": "TXT",
                                                        "name": "resend._domainkey",
                                                        "value": "p=MIGfMA0GCSq...",
                                                        "priority": null,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "MX",
                                                        "name": "send",
                                                        "value": "feedback-smtp.us-east-1.amazonses.com",
                                                        "priority": 10,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "TXT",
                                                        "name": "send",
                                                        "value": "v=spf1 include:amazonses.com ~all",
                                                        "priority": null,
                                                        "status": "verified"
                                                    }
                                                ]
                                            }
                                        ],
                                        "domain": "harbordental.com",
                                        "domain_status": "verified",
                                        "domain_region": "us-east-1",
                                        "from_address": "hello@harbordental.com",
                                        "from_name": "Harbor Dental",
                                        "team_senders": [
                                            {
                                                "user_id": 12,
                                                "name": "Eric Smith",
                                                "from": "eric@harbordental.com"
                                            },
                                            {
                                                "user_id": 15,
                                                "name": "Saad Khan",
                                                "from": "saad@harbordental.com"
                                            }
                                        ],
                                        "last_checked_at": "2026-10-18 09:00:00",
                                        "last_test_at": null,
                                        "last_error": null,
                                        "inbound": {
                                            "webhook_url": "https://app.example.com/webhooks/email/resend/AbC123",
                                            "webhook_created_for_you": true,
                                            "signing_secret_set": true,
                                            "address": "replies@abc123.resend.app",
                                            "suggested_address": null,
                                            "reply_address_example": "replies+c1234.1a2b3c4d5e6f@abc123.resend.app",
                                            "replies_come_back": true,
                                            "last_received_at": null
                                        },
                                        "next_step": "Sending from harbordental.com; replies land in the Inbox on the lead's conversation."
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Refused",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Use your business domain. Free email domains like gmail.com can't be added."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "domain": {
                                        "type": "string",
                                        "example": "harbordental.com"
                                    },
                                    "region": {
                                        "type": "string",
                                        "enum": [
                                            "us-east-1",
                                            "eu-west-1",
                                            "sa-east-1",
                                            "ap-northeast-1"
                                        ],
                                        "example": "us-east-1"
                                    },
                                    "receiving": {
                                        "type": "boolean",
                                        "example": false
                                    }
                                },
                                "required": [
                                    "domain"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/settings/resend/replies": {
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Turn on Resend replies",
                "description": "One step: creates the email.received webhook in the company's Resend account (pointing at data.inbound.webhook_url), keeps the signing secret it returns (never shown), and sets the reply address. inbound_address: the account's \u2026resend.app address or one on a receiving-enabled domain; omitted = replies@ the first verified receiving domain. From then on each lead email carries a Reply-To unique to that lead's conversation, so their reply lands on it in the Inbox and wakes a waiting \"Wait for reply\" step. Path: /api/settings/resend/replies.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Replies on",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "connected": true,
                                        "status": "active",
                                        "active": true,
                                        "key_last4": "a1B2",
                                        "domains": [
                                            {
                                                "name": "harbordental.com",
                                                "status": "verified",
                                                "region": "us-east-1",
                                                "receiving": "disabled",
                                                "selectable": true,
                                                "records": [
                                                    {
                                                        "purpose": "DKIM",
                                                        "type": "TXT",
                                                        "name": "resend._domainkey",
                                                        "value": "p=MIGfMA0GCSq...",
                                                        "priority": null,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "MX",
                                                        "name": "send",
                                                        "value": "feedback-smtp.us-east-1.amazonses.com",
                                                        "priority": 10,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "TXT",
                                                        "name": "send",
                                                        "value": "v=spf1 include:amazonses.com ~all",
                                                        "priority": null,
                                                        "status": "verified"
                                                    }
                                                ]
                                            }
                                        ],
                                        "domain": "harbordental.com",
                                        "domain_status": "verified",
                                        "domain_region": "us-east-1",
                                        "from_address": "hello@harbordental.com",
                                        "from_name": "Harbor Dental",
                                        "team_senders": [
                                            {
                                                "user_id": 12,
                                                "name": "Eric Smith",
                                                "from": "eric@harbordental.com"
                                            },
                                            {
                                                "user_id": 15,
                                                "name": "Saad Khan",
                                                "from": "saad@harbordental.com"
                                            }
                                        ],
                                        "last_checked_at": "2026-10-18 09:00:00",
                                        "last_test_at": null,
                                        "last_error": null,
                                        "inbound": {
                                            "webhook_url": "https://app.example.com/webhooks/email/resend/AbC123",
                                            "webhook_created_for_you": true,
                                            "signing_secret_set": true,
                                            "address": "replies@abc123.resend.app",
                                            "suggested_address": null,
                                            "reply_address_example": "replies+c1234.1a2b3c4d5e6f@abc123.resend.app",
                                            "replies_come_back": true,
                                            "last_received_at": null
                                        },
                                        "next_step": "Sending from harbordental.com; replies land in the Inbox on the lead's conversation."
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "No receiving address",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Enter the address replies should go to: your \u2026resend.app address (Resend \u2192 Emails \u2192 Receiving), or one on a domain with receiving turned on."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "inbound_address": {
                                        "type": "string",
                                        "example": "replies@abc123.resend.app"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/settings/resend/test": {
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Send a Resend test email",
                "description": "Sends a test email to the signed-in user, through exactly the path lead email takes (their From on the verified domain, Reply-To, plain-text part). Path: /api/settings/resend/test.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Sent",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Test email sent to amanda@harbordental.com.",
                                    "data": {
                                        "to": "amanda@harbordental.com",
                                        "from": "amanda@harbordental.com",
                                        "from_name": "Amanda Lee",
                                        "reply_to": "replies+c0.1a2b3c4d5e6f@abc123.resend.app",
                                        "message_id": "em_123"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not ready",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Choose a verified sending domain first."
                                }
                            }
                        }
                    },
                    {
                        "description": "Resend refused",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Resend didn't take the test email: The harbordental.com domain is not verified."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/settings/resend/senders": {
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Set a teammate's email sender",
                "description": "Account owner only. One teammate's lead email: send_as \"own\" (their own address on the domain, the default) or \"company\" (always the company address); local_part = the part before @ for their own address (\"\" = their login when it is on the domain, else their first name); reply_alerts = email them when one of their leads replies (default on). Only the fields sent change. data.team_senders shows every teammate's from, own_address, send_as, custom_local and reply_alerts. Path: /api/settings/resend/senders.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "connected": true,
                                        "status": "active",
                                        "active": true,
                                        "key_last4": "a1B2",
                                        "domains": [
                                            {
                                                "name": "harbordental.com",
                                                "status": "verified",
                                                "region": "us-east-1",
                                                "receiving": "disabled",
                                                "selectable": true,
                                                "records": [
                                                    {
                                                        "purpose": "DKIM",
                                                        "type": "TXT",
                                                        "name": "resend._domainkey",
                                                        "value": "p=MIGfMA0GCSq...",
                                                        "priority": null,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "MX",
                                                        "name": "send",
                                                        "value": "feedback-smtp.us-east-1.amazonses.com",
                                                        "priority": 10,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "TXT",
                                                        "name": "send",
                                                        "value": "v=spf1 include:amazonses.com ~all",
                                                        "priority": null,
                                                        "status": "verified"
                                                    }
                                                ]
                                            }
                                        ],
                                        "domain": "harbordental.com",
                                        "domain_status": "verified",
                                        "domain_region": "us-east-1",
                                        "from_address": "hello@harbordental.com",
                                        "from_name": "Harbor Dental",
                                        "team_senders": [
                                            {
                                                "user_id": 12,
                                                "name": "Eric Smith",
                                                "from": "eric@harbordental.com"
                                            },
                                            {
                                                "user_id": 15,
                                                "name": "Saad Khan",
                                                "from": "saad@harbordental.com"
                                            }
                                        ],
                                        "last_checked_at": "2026-10-18 09:00:00",
                                        "last_test_at": null,
                                        "last_error": null,
                                        "inbound": {
                                            "webhook_url": "https://app.example.com/webhooks/email/resend/AbC123",
                                            "webhook_created_for_you": true,
                                            "signing_secret_set": true,
                                            "address": "replies@abc123.resend.app",
                                            "suggested_address": null,
                                            "reply_address_example": "replies+c1234.1a2b3c4d5e6f@abc123.resend.app",
                                            "replies_come_back": true,
                                            "last_received_at": null
                                        },
                                        "next_step": "Sending from harbordental.com; replies land in the Inbox on the lead's conversation."
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Refused",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "eric@harbordental.com already belongs to Eric Smith. Pick another."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "user_id"
                                ],
                                "properties": {
                                    "user_id": {
                                        "type": "integer",
                                        "example": 42
                                    },
                                    "send_as": {
                                        "type": "string",
                                        "enum": [
                                            "own",
                                            "company"
                                        ]
                                    },
                                    "local_part": {
                                        "type": "string",
                                        "example": "eric"
                                    },
                                    "reply_alerts": {
                                        "type": "boolean",
                                        "example": true
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/settings/resend/check": {
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Re-check Resend",
                "description": "Asks Resend now: is the key still accepted, and is the chosen domain still verified? Domains not verified yet are re-verified and their DNS records refreshed (each record's status says which one is still missing). Sending stops automatically if the domain is no longer verified, and starts by itself once it is. Path: /api/settings/resend/check.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Checked",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "connected": true,
                                        "status": "active",
                                        "active": true,
                                        "key_last4": "a1B2",
                                        "domains": [
                                            {
                                                "name": "harbordental.com",
                                                "status": "verified",
                                                "region": "us-east-1",
                                                "receiving": "disabled",
                                                "selectable": true,
                                                "records": [
                                                    {
                                                        "purpose": "DKIM",
                                                        "type": "TXT",
                                                        "name": "resend._domainkey",
                                                        "value": "p=MIGfMA0GCSq...",
                                                        "priority": null,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "MX",
                                                        "name": "send",
                                                        "value": "feedback-smtp.us-east-1.amazonses.com",
                                                        "priority": 10,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "TXT",
                                                        "name": "send",
                                                        "value": "v=spf1 include:amazonses.com ~all",
                                                        "priority": null,
                                                        "status": "verified"
                                                    }
                                                ]
                                            }
                                        ],
                                        "domain": "harbordental.com",
                                        "domain_status": "verified",
                                        "domain_region": "us-east-1",
                                        "from_address": "hello@harbordental.com",
                                        "from_name": "Harbor Dental",
                                        "team_senders": [
                                            {
                                                "user_id": 12,
                                                "name": "Eric Smith",
                                                "from": "eric@harbordental.com"
                                            },
                                            {
                                                "user_id": 15,
                                                "name": "Saad Khan",
                                                "from": "saad@harbordental.com"
                                            }
                                        ],
                                        "last_checked_at": "2026-10-18 09:00:00",
                                        "last_test_at": null,
                                        "last_error": null,
                                        "inbound": {
                                            "webhook_url": "https://app.example.com/webhooks/email/resend/AbC123",
                                            "webhook_created_for_you": true,
                                            "signing_secret_set": true,
                                            "address": "replies@abc123.resend.app",
                                            "suggested_address": null,
                                            "reply_address_example": "replies+c1234.1a2b3c4d5e6f@abc123.resend.app",
                                            "replies_come_back": true,
                                            "last_received_at": null
                                        },
                                        "next_step": "Sending from harbordental.com; replies land in the Inbox on the lead's conversation."
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/settings/resend/inbound": {
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Set up Resend receiving",
                "description": "Saves the signing secret of the Resend webhook (event email.received, URL = data.inbound.webhook_url) and the receiving address used as Reply-To on lead email. Send \"\" to clear a value; omit a field to keep it. Path: /api/settings/resend/inbound.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "connected": true,
                                        "status": "active",
                                        "active": true,
                                        "key_last4": "a1B2",
                                        "domains": [
                                            {
                                                "name": "harbordental.com",
                                                "status": "verified",
                                                "region": "us-east-1",
                                                "receiving": "disabled",
                                                "selectable": true,
                                                "records": [
                                                    {
                                                        "purpose": "DKIM",
                                                        "type": "TXT",
                                                        "name": "resend._domainkey",
                                                        "value": "p=MIGfMA0GCSq...",
                                                        "priority": null,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "MX",
                                                        "name": "send",
                                                        "value": "feedback-smtp.us-east-1.amazonses.com",
                                                        "priority": 10,
                                                        "status": "verified"
                                                    },
                                                    {
                                                        "purpose": "SPF",
                                                        "type": "TXT",
                                                        "name": "send",
                                                        "value": "v=spf1 include:amazonses.com ~all",
                                                        "priority": null,
                                                        "status": "verified"
                                                    }
                                                ]
                                            }
                                        ],
                                        "domain": "harbordental.com",
                                        "domain_status": "verified",
                                        "domain_region": "us-east-1",
                                        "from_address": "hello@harbordental.com",
                                        "from_name": "Harbor Dental",
                                        "team_senders": [
                                            {
                                                "user_id": 12,
                                                "name": "Eric Smith",
                                                "from": "eric@harbordental.com"
                                            },
                                            {
                                                "user_id": 15,
                                                "name": "Saad Khan",
                                                "from": "saad@harbordental.com"
                                            }
                                        ],
                                        "last_checked_at": "2026-10-18 09:00:00",
                                        "last_test_at": null,
                                        "last_error": null,
                                        "inbound": {
                                            "webhook_url": "https://app.example.com/webhooks/email/resend/AbC123",
                                            "webhook_created_for_you": true,
                                            "signing_secret_set": true,
                                            "address": "replies@abc123.resend.app",
                                            "suggested_address": null,
                                            "reply_address_example": "replies+c1234.1a2b3c4d5e6f@abc123.resend.app",
                                            "replies_come_back": true,
                                            "last_received_at": null
                                        },
                                        "next_step": "Sending from harbordental.com; replies land in the Inbox on the lead's conversation."
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Enter the full receiving address, like replies@yourdomain.com."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "signing_secret": {
                                        "type": "string",
                                        "example": "whsec_xxxxxxxx"
                                    },
                                    "inbound_address": {
                                        "type": "string",
                                        "example": "replies@harbordental.com"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/settings/ghl/locations": {
            "get": {
                "tags": [
                    "Settings"
                ],
                "summary": "List LeadConnector locations",
                "description": "Connected LeadConnector locations for the company. Use `id` (base64 ghl_users row) with Sync Pipeline, and `location_id` as ghl_location_id on Pipeline APIs. Does **not** start OAuth connect, reconnect, or disconnect.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Connected locations",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "records": [
                                            {
                                                "id": "MQ==",
                                                "location_id": "ve9EPM428h8vShlRW1KT",
                                                "location_name": "Main Location",
                                                "is_default": true
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/settings/ghl/locations/{id}/sync-pipelines": {
            "post": {
                "tags": [
                    "Settings"
                ],
                "summary": "Sync Pipelines from LeadConnector",
                "description": "Same as Settings \u2192 Integration \u2192 LeadConnector \u2192 Sync Pipeline. Pulls that location's pipelines and stages into the workspace (new boards created, existing boards linked). Uses that location's token only; an agency/Company connection is exchanged to a location token automatically. `{id}` is the location row id from GET /api/settings/ghl/locations, or the LeadConnector locationId string. Does **not** connect or reconnect OAuth. 422 reconnect message only if that location still cannot be used \u2014 Re-Connect in the Settings UI.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Synced",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Synced pipelines from Main Location. 1 new, 2 linked, 8 stages.",
                                    "data": {
                                        "location_id": "ve9EPM428h8vShlRW1KT",
                                        "location_name": "Main Location",
                                        "created": 1,
                                        "linked": 2,
                                        "stages": 8
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "GHL location not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Sync failed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "GHL token is missing or expired. Re-Connect this location."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64 location row id from List LeadConnector locations, or the LeadConnector locationId",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/summary": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "All Metrics Summary",
                "description": "Returns all dashboard metrics as a paginated list of `{ key, value }` rows (same totals as before, one row per metric). Query `page` and `per_page` slice this list.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated summary",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "key": "date_range",
                                            "value": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            }
                                        },
                                        {
                                            "key": "total_leads",
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 11,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 11
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "appointment_disposition_id",
                        "in": "query",
                        "required": false,
                        "description": "Disposition ID for appointment metrics",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "transfer_disposition_id",
                        "in": "query",
                        "required": false,
                        "description": "Disposition ID for transfer metrics",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/total-leads": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Total Leads",
                "description": "Count of leads created in the date range. Returns one row in `data`; pagination totals reflect a single item.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated metric row",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "metric": "total_leads",
                                            "date_range": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            },
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/total-calls": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Total Calls",
                "description": "Outbound + inbound + voicemail call counts. Returns one row in `data`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated metric row",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "metric": "total_leads",
                                            "date_range": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            },
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/calls-per-lead": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Calls Per Lead",
                "description": "Average number of calls per lead. Returns one row in `data`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated metric row",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "metric": "total_leads",
                                            "date_range": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            },
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/speed-to-lead": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Speed to Lead",
                "description": "Average time from lead creation to first outbound call. Returns one row in `data`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated metric row",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "metric": "total_leads",
                                            "date_range": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            },
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/pickup-rate": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Pickup Rate",
                "description": "Percentage of outbound calls that were answered. Returns one row in `data`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated metric row",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "metric": "total_leads",
                                            "date_range": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            },
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/conversations-by-duration": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Conversations by Duration",
                "description": "Calls exceeding 1-5 minute thresholds. Returns one row in `data`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated metric row",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "metric": "total_leads",
                                            "date_range": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            },
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/callback-rate": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Callback Rate",
                "description": "Inbound callbacks as a percentage of total leads. Returns one row in `data`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated metric row",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "metric": "total_leads",
                                            "date_range": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            },
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/appointment-rate": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Appointment Rate",
                "description": "Appointment booking rate vs total leads. Returns one row in `data`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated appointment rate",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "metric": "total_leads",
                                            "date_range": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            },
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "appointment_disposition_id",
                        "in": "query",
                        "required": false,
                        "description": "Disposition ID to count as \"appointment\"",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/call-attempts-before-appt": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Call Attempts Before Appointment",
                "description": "Average calls made before a contact is set to appointment disposition. Returns one row in `data`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated avg attempts",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "metric": "total_leads",
                                            "date_range": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            },
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "appointment_disposition_id",
                        "in": "query",
                        "required": false,
                        "description": "Disposition ID for appointments",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/metrics/transfer-stats": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Transfer Stats",
                "description": "Transfer/live-transfer counts and rate. Returns one row in `data`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated transfer stats",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "metric": "total_leads",
                                            "date_range": {
                                                "start": "2026-05-06 00:00:00",
                                                "end": "2026-05-06 23:59:59"
                                            },
                                            "value": 42
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "date_range",
                        "in": "query",
                        "required": false,
                        "description": "Date range preset (Today, Yesterday, Last 7 Days, etc.)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom start date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_date",
                        "in": "query",
                        "required": false,
                        "description": "Custom end date (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "agent_id",
                        "in": "query",
                        "required": false,
                        "description": "Agent user ID or \"All\"",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "transfer_disposition_id",
                        "in": "query",
                        "required": false,
                        "description": "Disposition ID for transfers",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/filters/dispositions": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Filter: Dispositions",
                "description": "Paginated list of dispositions for filter dropdowns.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated dispositions",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": 1,
                                            "disposition": "Appointment Set"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/dashboard/filters/agents": {
            "get": {
                "tags": [
                    "Dashboard"
                ],
                "summary": "Filter: Agents",
                "description": "Paginated list of dialer agents for filter dropdowns.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Paginated agents",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": 1,
                                            "name": "Agent Name",
                                            "profile_img": null,
                                            "availabilty": "Available"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 15,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (max 30, default 15)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/reports/calls": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "List & Filter Calls",
                "description": "Paginated list of call logs with optional filters: direction, status, sentiment, date range, search.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Calls list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "MTIz",
                                            "contact_id": "NDU2",
                                            "contact_name": "John Doe",
                                            "phone_number": "+14155550100",
                                            "direction": "outbound",
                                            "from_number": "+18885551234",
                                            "to_number": "+14155550100",
                                            "status": "answered",
                                            "call_duration": 120,
                                            "recording_url": "https://example.com/rec.mp3",
                                            "sentiment": "positive",
                                            "created_at": "2026-05-01 10:00:00"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 20,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Search by contact name or phone number",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "description": "Filter by direction: inbound | outbound",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filter by call status (e.g. answered, no-answer, busy, failed)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sentiment",
                        "in": "query",
                        "required": false,
                        "description": "Filter by user sentiment",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "description": "Start date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "description": "End date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (default 20, max 100)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/reports/calls/{id}": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Get Call Detail",
                "description": "Retrieve full detail of a single call log by its base64-encoded ID.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Call detail",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "id": "MTIz",
                                        "contact_id": "NDU2",
                                        "contact_name": "John Doe",
                                        "phone_number": "+14155550100",
                                        "email": "john@example.com",
                                        "direction": "outbound",
                                        "from_number": "+18885551234",
                                        "to_number": "+14155550100",
                                        "status": "answered",
                                        "call_duration": 120,
                                        "recording_url": "https://example.com/rec.mp3",
                                        "sentiment": "positive",
                                        "created_at": "2026-05-01 10:00:00"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Call record not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64-encoded call log ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/reports/calls/filters/agents": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Filter: Agents",
                "description": "List of dialer agents for call report filter dropdowns. Same rules as GET /api/dashboard/filters/agents: company users with dialer enabled. Fields: id (Base64-encoded user id, same convention as report log ids), name, profile_img, availabilty.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Agents list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "agents": [
                                        {
                                            "id": "MQ==",
                                            "name": "Agent Name",
                                            "profile_img": null,
                                            "availabilty": "Available"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/reports/calls/filters/call-status": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Filter: Call Status",
                "description": "Returns every allowed call status value for report filter dropdowns \u2014 same enum set as GET /api/disposition/meta/call-status-options and the Manage Dispositions Call Status field. Use with the `status` query param on List / Summary / Export when values match your stored contact log `status`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Call status options",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "options": [
                                            "No",
                                            "Ringing",
                                            "Answered",
                                            "Busy",
                                            "Canceled",
                                            "No-answer",
                                            "In-Progress",
                                            "Failed",
                                            "AMD",
                                            "Completed"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/reports/calls/filters/date-ranges": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Filter: Date Ranges",
                "description": "Preset labels for date filter dropdowns \u2014 same values accepted as the `date_range` query param on dashboard metrics. Call Reports endpoints use `date_from` / `date_to` (Y-m-d); map presets to those dates in the client when needed.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Date range presets",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "options": [
                                            "Today",
                                            "Yesterday",
                                            "Last 7 Days",
                                            "Last Week Sun",
                                            "Last Week Mon",
                                            "Last Business Week",
                                            "This Week Sun",
                                            "This Week Mon",
                                            "Last 14 Days",
                                            "This Month",
                                            "Last Month",
                                            "Last 30 Days",
                                            "Last Year"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/reports/calls/export-csv": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Export Calls CSV",
                "description": "Download call logs as a CSV file. Uses the same filter query parameters as List & Filter Calls (search, direction, status, sentiment, date_from, date_to). Does not paginate \u2014 exports all matching rows.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "CSV file download",
                        "content": {
                            "text/csv": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Search by contact name or phone number",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "description": "Filter by direction: inbound | outbound",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filter by call status (e.g. answered, no-answer, busy, failed)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sentiment",
                        "in": "query",
                        "required": false,
                        "description": "Filter by user sentiment",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "description": "Start date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "description": "End date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/reports/calls/summary": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Summary Stats",
                "description": "Aggregate call statistics for the current filters: total calls, unique contacts, total and average call duration (seconds), counts grouped by direction and by status. Same filter query parameters as List & Filter Calls.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Summary stats",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "total_calls": 150,
                                        "unique_contacts": 45,
                                        "total_duration_seconds": 12450,
                                        "avg_duration_seconds": 83,
                                        "by_direction": {
                                            "Inbound": 60,
                                            "Outbound": 90
                                        },
                                        "by_status": {
                                            "answered": 100,
                                            "no-answer": 50
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Search by contact name or phone number",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "description": "Filter by direction: inbound | outbound",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filter by call status (e.g. answered, no-answer, busy, failed)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sentiment",
                        "in": "query",
                        "required": false,
                        "description": "Filter by user sentiment",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "description": "Start date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "description": "End date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/reports/sms": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "List & Filter SMS",
                "description": "Paginated SMS message logs from contact_logs (type SMS) with optional filters: search (contact name/phone), direction, status, sentiment, date_from, date_to.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "SMS list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": [
                                        {
                                            "id": "MTIz",
                                            "contact_id": "NDU2",
                                            "contact_name": "John Doe",
                                            "phone_number": "+14155550100",
                                            "direction": "outbound",
                                            "from_number": "+18885551234",
                                            "to_number": "+14155550100",
                                            "status": "delivered",
                                            "message": "Hello!",
                                            "sentiment": null,
                                            "created_at": "2026-05-01 10:00:00"
                                        }
                                    ],
                                    "pagination": {
                                        "total": 1,
                                        "current_page": 1,
                                        "per_page": 20,
                                        "last_page": 1,
                                        "from": 1,
                                        "to": 1
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Search by contact name or phone number",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "description": "Filter by direction: inbound | outbound",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filter by SMS / delivery status",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sentiment",
                        "in": "query",
                        "required": false,
                        "description": "Filter by user sentiment",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "description": "Start date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "description": "End date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Items per page (default 20, max 100)",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/reports/sms/filters/sms-status": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Filter: SMS Status",
                "description": "Typical `status` values stored on SMS contact_logs for filter dropdowns (Plivo inbound/outbound, GHL, workflow). Match the exact string stored when filtering List / Summary / Export.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "SMS status options",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "options": [
                                            "Received",
                                            "Sent",
                                            "Delivered",
                                            "delivered",
                                            "queued",
                                            "failed",
                                            "undelivered"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/reports/sms/filters/agents": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Filter: SMS Agents",
                "description": "List of dialer agents for SMS report filter dropdowns \u2014 same payload as GET /api/reports/calls/filters/agents (each agent id is Base64-encoded).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Agents list",
                        "content": {
                            "application/json": {
                                "example": {
                                    "agents": [
                                        {
                                            "id": "MQ==",
                                            "name": "Agent Name",
                                            "profile_img": null,
                                            "availabilty": "Available"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/reports/sms/filters/date-ranges": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Filter: SMS Date Ranges",
                "description": "Same preset `date_range` labels as GET /api/reports/calls/filters/date-ranges; use with client-side mapping to `date_from` / `date_to` on SMS report endpoints.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Date range presets",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "data": {
                                        "options": [
                                            "Today",
                                            "Yesterday",
                                            "Last 7 Days",
                                            "Last Week Sun",
                                            "Last Week Mon",
                                            "Last Business Week",
                                            "This Week Sun",
                                            "This Week Mon",
                                            "Last 14 Days",
                                            "This Month",
                                            "Last Month",
                                            "Last 30 Days",
                                            "Last Year"
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/reports/sms/export-csv": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Export SMS CSV",
                "description": "Download SMS logs as a CSV file. Same filter query parameters as List & Filter SMS (search, direction, status, sentiment, date_from, date_to). Exports all matching rows (no pagination).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "CSV file download",
                        "content": {
                            "text/csv": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Search by contact name or phone number",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "description": "Filter by direction: inbound | outbound",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filter by SMS / delivery status",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sentiment",
                        "in": "query",
                        "required": false,
                        "description": "Filter by user sentiment",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "description": "Start date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "description": "End date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/reports/sms/summary": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "SMS Summary Stats",
                "description": "Aggregate SMS statistics for the current filters: total messages, unique contacts, counts by direction and by status. Same filter query parameters as List & Filter SMS.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "SMS summary",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "total_messages": 500,
                                        "unique_contacts": 120,
                                        "by_direction": {
                                            "Inbound": 200,
                                            "Outbound": 300
                                        },
                                        "by_status": {
                                            "delivered": 450,
                                            "failed": 50
                                        }
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Search by contact name or phone number",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "required": false,
                        "description": "Filter by direction: inbound | outbound",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filter by SMS / delivery status",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sentiment",
                        "in": "query",
                        "required": false,
                        "description": "Filter by user sentiment",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "description": "Start date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "description": "End date filter (Y-m-d)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/reports/sms/{id}": {
            "get": {
                "tags": [
                    "Reports"
                ],
                "summary": "Get SMS Detail",
                "description": "Retrieve full detail of a single SMS log by its base64-encoded ID.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "SMS detail",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "data": {
                                        "id": "MTIz",
                                        "contact_id": "NDU2",
                                        "contact_name": "John Doe",
                                        "phone_number": "+14155550100",
                                        "email": "john@example.com",
                                        "direction": "outbound",
                                        "from_number": "+18885551234",
                                        "to_number": "+14155550100",
                                        "status": "delivered",
                                        "message": "Hello!",
                                        "sentiment": null,
                                        "created_at": "2026-05-01 10:00:00"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "SMS record not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Base64-encoded SMS log ID",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/google-ads/status": {
            "get": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Google Ads status",
                "description": "Overview snapshot for the company Google Ads connection (same as Marketing \u2192 Google Ads Overview). Not connected returns connected=false. MCC login headers are handled by the server (REST v25). Connect/disconnect is not on this endpoint.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Status",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "connected": true,
                                    "connection": {
                                        "display_name": "Ads User",
                                        "status": "active",
                                        "needs_reconnect": false,
                                        "token_expires_at": "2026-09-22T12:00:00+00:00",
                                        "connected_at": "2026-09-11T10:00:00+00:00"
                                    },
                                    "test_access_only": false,
                                    "webhook_url": "https://app.rizzdial.com/webhooks/google-ads/leads",
                                    "webhook_key_set": true,
                                    "customers": [
                                        {
                                            "customer_id": "3514082235",
                                            "descriptive_name": "Long Island Weight Loss Institute",
                                            "status": "ENABLED",
                                            "currency_code": "USD",
                                            "time_zone": "America/New_York",
                                            "manager": false,
                                            "test_account": false
                                        }
                                    ],
                                    "lead_forms": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/marketing/google-ads/sync": {
            "post": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Sync Google Ads assets",
                "description": "Same as Sync Assets: accessible customers, names, MCC children, Lead Form assets.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Synced",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "summary": {
                                        "customers": 5,
                                        "lead_forms": 2,
                                        "test_access_only": false
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads is not connected."
                                }
                            }
                        }
                    },
                    {
                        "description": "Google rejected the sync",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads request failed.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/marketing/google-ads/customers": {
            "get": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "List Google Ads customers",
                "description": "Ad accounts for this company. Includes manager accounts (manager=true). refresh=1 runs Sync Assets first.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Customers",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "connected": true,
                                    "test_access_only": false,
                                    "customers": [
                                        {
                                            "customer_id": "3514082235",
                                            "descriptive_name": "Long Island Weight Loss Institute",
                                            "status": "ENABLED",
                                            "currency_code": "USD",
                                            "time_zone": "America/New_York",
                                            "manager": false,
                                            "test_account": false
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Refresh from Google failed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not refresh customers. Reconnect Google Ads if this continues.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "refresh",
                        "in": "query",
                        "required": false,
                        "description": "Set to 1 to re-sync from Google before listing",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/marketing/google-ads/customers/{customerId}/campaigns": {
            "get": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "List campaigns",
                "description": "Live campaigns for a company-owned customer (not REMOVED). customerId is digits only.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Campaigns",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "campaigns": [
                                        {
                                            "id": "99",
                                            "name": "Leads",
                                            "status": "PAUSED",
                                            "advertising_channel_type": "SEARCH",
                                            "budget": 10
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign customer",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Customer not found for this company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected or expired",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads login expired. Reconnect in Settings.",
                                    "requires_reconnect": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads request failed.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "customerId",
                        "in": "path",
                        "required": true,
                        "description": "Google Ads customer id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Create paused campaign",
                "description": "Creates a Search campaign by default. Status defaults to PAUSED so spend does not start. Ads and targeting stay in Google Ads.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "campaign": {
                                        "id": "99",
                                        "resource_name": "customers/3514082235/campaigns/99",
                                        "status": "PAUSED"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign customer",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Customer not found for this company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads login expired. Reconnect in Settings.",
                                    "requires_reconnect": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads request failed.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "customerId",
                        "in": "path",
                        "required": true,
                        "description": "Google Ads customer id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/GoogleAdsCreateCampaignRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/google-ads/campaigns/{campaignId}": {
            "patch": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Update campaign",
                "description": "Rename and/or pause/resume. customer_id is required in the JSON body.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign customer",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Customer not found for this company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Nothing to update, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Nothing to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads request failed.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaignId",
                        "in": "path",
                        "required": true,
                        "description": "Google campaign id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/GoogleAdsUpdateCampaignRequest"
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Update campaign (POST)",
                "description": "Same as PATCH /campaigns/{campaignId}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Nothing to update, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Nothing to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads request failed.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaignId",
                        "in": "path",
                        "required": true,
                        "description": "Google campaign id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/GoogleAdsUpdateCampaignRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/google-ads/campaigns/{campaignId}/ad-groups": {
            "get": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "List ad groups",
                "description": "Ad groups for a campaign. Pass customer_id as query (or JSON body).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Ad groups",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "ad_groups": [
                                        {
                                            "id": "111",
                                            "name": "Ad group 1",
                                            "status": "PAUSED"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign customer",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Customer not found for this company."
                                }
                            }
                        }
                    },
                    {
                        "description": "customer_id required or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "customer_id is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads request failed.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaignId",
                        "in": "path",
                        "required": true,
                        "description": "Google campaign id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "customer_id",
                        "in": "query",
                        "required": true,
                        "description": "Google Ads customer id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/google-ads/customers/{customerId}/ads": {
            "get": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "List ads",
                "description": "Live ads for the customer. Optional campaign_id filter. Pause/resume needs ad_group_id from ad_group.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Ads",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "ads": [
                                        {
                                            "id": "222",
                                            "name": "RSA",
                                            "status": "PAUSED",
                                            "ad_group": "customers/3514082235/adGroups/111",
                                            "campaign_id": "99",
                                            "campaign": "Leads"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign customer",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Customer not found for this company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected or expired",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads login expired. Reconnect in Settings.",
                                    "requires_reconnect": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads request failed.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "customerId",
                        "in": "path",
                        "required": true,
                        "description": "Google Ads customer id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "campaign_id",
                        "in": "query",
                        "required": false,
                        "description": "Optional campaign id filter",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/google-ads/ads/{adId}": {
            "patch": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Pause or resume ad",
                "description": "Pause or resume an existing ad. Image ads are created on POST /customers/{customerId}/image-ads. customer_id and ad_group_id are required.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign customer",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Customer not found for this company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Missing ad_group_id or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "ad_group_id is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads request failed.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "adId",
                        "in": "path",
                        "required": true,
                        "description": "Google ad id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/GoogleAdsUpdateAdRequest"
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Pause or resume ad (POST)",
                "description": "Same as PATCH /ads/{adId}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Missing ad_group_id or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "ad_group_id is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads request failed.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "adId",
                        "in": "path",
                        "required": true,
                        "description": "Google ad id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/GoogleAdsUpdateAdRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/google-ads/customers/{customerId}/insights": {
            "get": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Campaign insights",
                "description": "Last 7 days by default (since=today-6, until=today). leads is Google conversions, not PowerList contacts.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Insights",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "since": "2026-09-15",
                                    "until": "2026-09-21",
                                    "insights": [
                                        {
                                            "id": "99",
                                            "dimensions": {
                                                "campaign_id": "99",
                                                "campaign": "Leads"
                                            },
                                            "metrics": {
                                                "spend": 12.5,
                                                "impressions": 1000,
                                                "clicks": 40,
                                                "leads": 2,
                                                "cpl": 6.25
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign customer",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Customer not found for this company."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected or expired",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads login expired. Reconnect in Settings.",
                                    "requires_reconnect": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Google Ads request failed.",
                                    "requires_reconnect": false
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "customerId",
                        "in": "path",
                        "required": true,
                        "description": "Google Ads customer id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "description": "Start date Y-m-d (default today minus 6 days)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "until",
                        "in": "query",
                        "required": false,
                        "description": "End date Y-m-d (default today)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/google-ads/lead-forms": {
            "get": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "List Lead Forms",
                "description": "Synced Lead Forms. webhook_url must be pasted on each form in Google Ads with the platform webhook key. Leads On here is local only.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Lead Forms",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "connected": true,
                                    "webhook_url": "https://app.rizzdial.com/webhooks/google-ads/leads",
                                    "lead_forms": [
                                        {
                                            "form_id": "form-1",
                                            "customer_id": "3514082235",
                                            "asset_resource_name": "customers/3514082235/assets/1",
                                            "name": "Leads",
                                            "status": "ENABLED",
                                            "subscribed": true,
                                            "power_list_id": null,
                                            "power_list_name": null
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/marketing/google-ads/lead-forms/{formId}/subscribe": {
            "post": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Lead Form Leads On",
                "description": "Marks the form locally. Still paste webhook_url on the Google Lead Form.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Leads On",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "subscribed": true,
                                    "webhook_url": "https://app.rizzdial.com/webhooks/google-ads/leads",
                                    "message": "Leads On. Paste the webhook URL onto this Lead Form in Google Ads, and set google_key to the Google Ads webhook key for this platform."
                                }
                            }
                        }
                    },
                    {
                        "description": "Form not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "formId",
                        "in": "path",
                        "required": true,
                        "description": "form_id or asset_resource_name (URL-encoded)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/google-ads/lead-forms/{formId}/unsubscribe": {
            "post": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Lead Form Leads Off",
                "description": "Stops storing new leads from this form in AI Sync.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Leads Off",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "subscribed": false,
                                    "webhook_url": "https://app.rizzdial.com/webhooks/google-ads/leads",
                                    "message": "Leads Off."
                                }
                            }
                        }
                    },
                    {
                        "description": "Form not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "formId",
                        "in": "path",
                        "required": true,
                        "description": "form_id or asset_resource_name (URL-encoded)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/google-ads/lead-forms/{formId}/power-list": {
            "post": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Assign Lead Form PowerList",
                "description": "Empty/null power_list_id uses the company Default PowerList.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Assigned",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "power_list_id": 1,
                                    "power_list_name": "Inbound"
                                }
                            }
                        }
                    },
                    {
                        "description": "Form or PowerList not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "formId",
                        "in": "path",
                        "required": true,
                        "description": "form_id or asset_resource_name (URL-encoded)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/GoogleAdsAssignPowerListRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/google-ads/lead-forms/{formId}/fields": {
            "get": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "List Lead Form fields",
                "description": "Google questions plus contact columns (rizzdial_fields) for mapping.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Fields",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "form_id": "form-1",
                                    "form_name": "Leads",
                                    "fields": [
                                        {
                                            "id": 1,
                                            "google_field_id": "EMAIL",
                                            "label": "Email",
                                            "field_type": "EMAIL",
                                            "rizzdial_field": "email"
                                        }
                                    ],
                                    "rizzdial_fields": [
                                        "first_name",
                                        "email",
                                        "phone_number"
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Form not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "formId",
                        "in": "path",
                        "required": true,
                        "description": "form_id or asset_resource_name (URL-encoded)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/google-ads/lead-forms/{formId}/fields/mapping": {
            "post": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Save Lead Form field mapping",
                "description": "Map Google question ids to contact columns. Empty/null skips that question.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Form not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "formId",
                        "in": "path",
                        "required": true,
                        "description": "form_id or asset_resource_name (URL-encoded)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/GoogleAdsLeadFormMappingRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/connections": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "List Facebook connections",
                "description": "Every Facebook connection of this company. The `connection` value is what you send as X-Meta-Connection on the other calls. Tokens are never returned.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Connections",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "connections": [
                                        {
                                            "connection": "eyJpdiI6Ij...",
                                            "fb_user_id": "1001",
                                            "fb_user_name": "Ali Khan",
                                            "status": "active",
                                            "is_external": false,
                                            "token_expires_at": "2026-12-01T00:00:00+00:00",
                                            "connected_at": "2026-10-01T10:00:00+00:00",
                                            "ad_accounts_count": 2,
                                            "pages_count": 3
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/status": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Connected assets snapshot",
                "description": "Connection, businesses (with External Link per business), ad accounts, Pages and Lead Forms for the selected connection. Reads the local database only; use POST /sync to refresh from Facebook.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Status",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "connected": true,
                                    "connection": {
                                        "fb_user_id": "1001",
                                        "fb_user_name": "Ali Khan",
                                        "status": "active",
                                        "token_expires_at": null,
                                        "connected_at": "2026-10-01T10:00:00+00:00"
                                    },
                                    "businesses": [],
                                    "ad_accounts": [
                                        {
                                            "meta_account_id": "act_111",
                                            "name": "Main",
                                            "currency": "USD",
                                            "account_status": 1,
                                            "meta_business_id": null
                                        }
                                    ],
                                    "pages": [
                                        {
                                            "page_id": "5550001",
                                            "page_name": "Test Page",
                                            "category": "Business",
                                            "subscribed": true,
                                            "subscribed_at": null
                                        }
                                    ],
                                    "lead_forms": [
                                        {
                                            "form_id": "9990001",
                                            "name": "Spring",
                                            "status": "ACTIVE",
                                            "leads_count": 4,
                                            "page_id": "5550001",
                                            "page_name": "Test Page",
                                            "power_list_id": null,
                                            "power_list_name": null,
                                            "last_synced_at": null
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/sync": {
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Sync assets from Facebook",
                "description": "Re-discovers businesses, ad accounts, Pages and Lead Forms for the selected connection.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Synced",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "summary": {
                                        "ad_accounts": 2,
                                        "pages": 3
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "connected": false,
                                    "message": "Facebook is not connected for this account."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/ad-accounts": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "List ad accounts",
                "description": "Ad accounts of the selected connection. refresh=1 re-syncs from Facebook first. Not connected returns connected=false with an empty list (still 200).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Ad accounts",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "connected": true,
                                    "ad_accounts": [
                                        {
                                            "meta_account_id": "act_111",
                                            "account_id": "111",
                                            "name": "Main Ad Account",
                                            "currency": "USD",
                                            "account_status": 1,
                                            "timezone_name": "America/New_York",
                                            "meta_business_id": null
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Reconnect needed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "refresh",
                        "in": "query",
                        "required": false,
                        "description": "Set to 1 to re-sync from Facebook before listing",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/pages": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "List Pages with Lead Forms",
                "description": "Pages of the selected connection with their Instant Forms nested. refresh=1 re-syncs from Facebook first.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Pages",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "connected": true,
                                    "fb_user": "Ali Khan",
                                    "pages": [
                                        {
                                            "page_id": "5550001",
                                            "page_name": "Test Page",
                                            "category": "Business",
                                            "subscribed": true,
                                            "subscribed_at": "2026-10-02T10:00:00+00:00",
                                            "tasks": [
                                                "ADVERTISE"
                                            ],
                                            "lead_forms": [
                                                {
                                                    "form_id": "9990001",
                                                    "name": "Spring",
                                                    "status": "ACTIVE",
                                                    "leads_count": 4,
                                                    "last_synced_at": null,
                                                    "power_list_id": 12,
                                                    "power_list_name": "Inbound",
                                                    "fields_count": 3
                                                }
                                            ]
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Refresh failed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not refresh your Facebook Pages. The Facebook login may have expired - try Reconnecting."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "refresh",
                        "in": "query",
                        "required": false,
                        "description": "Set to 1 to re-sync from Facebook before listing",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/pages/{pageId}/subscribe": {
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Turn on lead delivery for a Page",
                "description": "Subscribes the Page to leadgen so new leads reach AI Sync. If Facebook refuses for permission reasons the response is 422 with requires_manual=true and the manual steps.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Subscribed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Page not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Page not found. Reload the list and try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Manual setup needed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_manual": true,
                                    "page_id": "5550001",
                                    "message": "Lead delivery for Test Page needs to be turned on manually in Facebook (takes 30 seconds)."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "pageId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook Page id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/pages/{pageId}/unsubscribe": {
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Turn off lead delivery for a Page",
                "description": "Unsubscribes the Page from leadgen.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Unsubscribed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Page not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Page not found. Reload the list and try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "pageId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook Page id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/lead-forms": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "List Instant (Lead) Forms",
                "description": "Instant Forms synced from the Pages of the selected connection, with the PowerList each one delivers into. Not the Marketing Lead Form (hosted/JS/cURL) feature.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Lead Forms",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "connected": true,
                                    "lead_forms": [
                                        {
                                            "form_id": "9990001",
                                            "name": "Spring",
                                            "status": "ACTIVE",
                                            "leads_count": 4,
                                            "page_id": "5550001",
                                            "page_name": "Test Page",
                                            "subscribed": true,
                                            "power_list_id": 12,
                                            "power_list_name": "Inbound",
                                            "last_synced_at": null
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/pages/{pageId}/lead-forms": {
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Create an Instant (Lead) Form on a Page",
                "description": "Creates the form on Facebook with standard contact questions, saves it locally and syncs its fields. Needs the pages_manage_ads permission (422 requires_reconnect if missing) and does not work on connections that return no Pages (External).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "form": {
                                        "form_id": "9990001",
                                        "name": "Spring Offer - Get a Quote"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Page not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Page not found. Reload the list and try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "pageId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook Page id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsCreateLeadFormRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/lead-forms/{formId}/power-list": {
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Assign Lead Form PowerList",
                "description": "Leads from this form are added to the PowerList. Empty or null power_list_id detaches it.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Assigned",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "form_id": "9990001",
                                    "power_list_id": 12,
                                    "power_list_name": "Inbound"
                                }
                            }
                        }
                    },
                    {
                        "description": "Form not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Lead Form not found. Try Sync Assets and retry."
                                }
                            }
                        }
                    },
                    {
                        "description": "PowerList not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Selected PowerList not found for this account."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "formId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook Lead Form id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsAssignPowerListRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/lead-forms/{formId}/fields": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "List Lead Form fields",
                "description": "Synced Facebook questions plus the company contact columns (rizzdial_fields) they can be mapped to.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Fields",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "form_id": "9990001",
                                    "form_name": "Spring",
                                    "fields": [
                                        {
                                            "id": 1,
                                            "field_key": "email",
                                            "field_label": "Email",
                                            "field_type": "EMAIL",
                                            "rizzdial_field": "email"
                                        }
                                    ],
                                    "rizzdial_fields": [
                                        "first_name",
                                        "email",
                                        "phone_number"
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Form not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Lead Form not found. Try Sync Assets and retry."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "formId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook Lead Form id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/lead-forms/{formId}/fields/mapping": {
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Save Lead Form field mapping",
                "description": "Maps Facebook question keys to contact columns. Unknown keys are skipped; unknown columns are returned in `rejected`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "updated": 3,
                                    "rejected": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Form not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Lead Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "No mappings",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "No mappings supplied."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "formId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook Lead Form id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsLeadFormMappingRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/ad-accounts/{actId}/campaigns": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "List campaigns",
                "description": "Live from Facebook. Each campaign carries budget fields, `delivery_issues` (Meta's own wording) and `needs_attention`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Campaigns",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "campaigns": [
                                        {
                                            "id": "120200000000001",
                                            "name": "Spring leads",
                                            "objective": "OUTCOME_LEADS",
                                            "status": "PAUSED",
                                            "effective_status": "PAUSED",
                                            "daily_budget": "5000",
                                            "lifetime_budget": null,
                                            "budget_remaining": "5000",
                                            "delivery_issues": [],
                                            "needs_attention": false
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected / ad account not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Ad Account not found for this workspace. Refresh Ad Accounts and try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Reconnect needed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "actId",
                        "in": "path",
                        "required": true,
                        "description": "Graph ad account id including the act_ prefix (e.g. act_123456789)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Create campaign",
                "description": "Creates a campaign, PAUSED by default. Budgets live on the ad sets.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "campaign": {
                                        "id": "120200000000001"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected / ad account not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Ad Account not found for this workspace. Refresh Ad Accounts and try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "actId",
                        "in": "path",
                        "required": true,
                        "description": "Graph ad account id including the act_ prefix (e.g. act_123456789)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsCreateCampaignRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/campaigns/{campaignId}": {
            "patch": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Update campaign",
                "description": "Rename and/or pause/resume. Ownership is checked before Facebook is changed.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": {
                                        "success": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign object",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This object does not belong to an Ad Account on this workspace."
                                }
                            }
                        }
                    },
                    {
                        "description": "Nothing to update, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Nothing to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "campaignId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook campaign id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsUpdateRequest"
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Update campaign (POST)",
                "description": "Same as PATCH /campaigns/{campaignId}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": {
                                        "success": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign object",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This object does not belong to an Ad Account on this workspace."
                                }
                            }
                        }
                    },
                    {
                        "description": "Nothing to update, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Nothing to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "campaignId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook campaign id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsUpdateRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/campaigns/{campaignId}/adsets": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "List ad sets",
                "description": "Ad sets of a campaign with budget, schedule, targeting, `delivery_issues` and `needs_attention`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Ad sets",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "adsets": [
                                        {
                                            "id": "120200000000002",
                                            "name": "US 25-55",
                                            "campaign_id": "120200000000001",
                                            "status": "PAUSED",
                                            "effective_status": "PAUSED",
                                            "daily_budget": "2000",
                                            "optimization_goal": "LEAD_GENERATION",
                                            "billing_event": "IMPRESSIONS",
                                            "targeting": {
                                                "geo_locations": {
                                                    "countries": [
                                                        "US"
                                                    ]
                                                },
                                                "age_min": 25,
                                                "age_max": 55
                                            },
                                            "delivery_issues": [],
                                            "needs_attention": false
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign object",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This object does not belong to an Ad Account on this workspace."
                                }
                            }
                        }
                    },
                    {
                        "description": "Reconnect needed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "campaignId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook campaign id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Create ad set",
                "description": "Creates an ad set with budget, schedule and targeting. PAUSED by default. LEAD_GENERATION runs on the Page (destination ON_AD). Budgets are in whole currency units and assume a 2-decimal currency.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "adset": {
                                        "id": "120200000000002"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign object",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This object does not belong to an Ad Account on this workspace."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "campaignId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook campaign id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsCreateAdSetRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/adsets/{adsetId}": {
            "patch": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Update ad set",
                "description": "Rename, pause/resume, change budget, schedule or targeting. Send only what changes. At least one field is required.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": {
                                        "success": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign object",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This object does not belong to an Ad Account on this workspace."
                                }
                            }
                        }
                    },
                    {
                        "description": "Nothing to update, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Nothing to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "adsetId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook ad set id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsUpdateAdSetRequest"
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Update ad set (POST)",
                "description": "Same as PATCH /adsets/{adsetId}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": {
                                        "success": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign object",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This object does not belong to an Ad Account on this workspace."
                                }
                            }
                        }
                    },
                    {
                        "description": "Nothing to update, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Nothing to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "adsetId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook ad set id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsUpdateAdSetRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/adsets/{adsetId}/duplicate": {
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Duplicate ad set",
                "description": "Copies the ad set and its ads. The copy is PAUSED and named \"... - Copy\". Optional target_id is the campaign to copy into.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Duplicated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": {
                                        "copied_adset_id": "120200000000009"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign object",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This object does not belong to an Ad Account on this workspace."
                                }
                            }
                        }
                    },
                    {
                        "description": "Reconnect needed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "adsetId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook ad set id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsDuplicateRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/ad-accounts/{actId}/ads": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "List ads",
                "description": "Ads of an ad account. Optional campaign_id / adset_id filters. Rejected ads carry Meta's reason in `delivery_issues`.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Ads",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "ads": [
                                        {
                                            "id": "120200000000004",
                                            "name": "Spring ad 1",
                                            "campaign_id": "120200000000001",
                                            "adset_id": "120200000000002",
                                            "status": "ACTIVE",
                                            "effective_status": "DISAPPROVED",
                                            "delivery_issues": [
                                                {
                                                    "summary": "Rejected: Personal attributes",
                                                    "message": "This ad makes assumptions about people."
                                                }
                                            ],
                                            "needs_attention": true
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected / ad account not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Ad Account not found for this workspace. Refresh Ad Accounts and try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Reconnect needed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "actId",
                        "in": "path",
                        "required": true,
                        "description": "Graph ad account id including the act_ prefix (e.g. act_123456789)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "campaign_id",
                        "in": "query",
                        "required": false,
                        "description": "Only ads in this campaign",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "adset_id",
                        "in": "query",
                        "required": false,
                        "description": "Only ads in this ad set",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Create ad",
                "description": "Creates an ad in an existing ad set from an existing creative. PAUSED by default.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "ad": {
                                        "id": "120200000000004"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected / ad account not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Ad Account not found for this workspace. Refresh Ad Accounts and try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "actId",
                        "in": "path",
                        "required": true,
                        "description": "Graph ad account id including the act_ prefix (e.g. act_123456789)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsCreateAdRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/ads/{adId}": {
            "patch": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Update ad",
                "description": "Rename and/or pause/resume. Ownership is checked before Facebook is changed.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": {
                                        "success": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign object",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This object does not belong to an Ad Account on this workspace."
                                }
                            }
                        }
                    },
                    {
                        "description": "Nothing to update, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Nothing to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "adId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook ad id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsUpdateRequest"
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Update ad (POST)",
                "description": "Same as PATCH /ads/{adId}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": {
                                        "success": true
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign object",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This object does not belong to an Ad Account on this workspace."
                                }
                            }
                        }
                    },
                    {
                        "description": "Nothing to update, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Nothing to update."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "adId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook ad id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsUpdateRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/ads/{adId}/duplicate": {
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Duplicate ad",
                "description": "Copies the ad. The copy is PAUSED and named \"... - Copy\". Optional target_id is the ad set to copy into.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Duplicated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "result": {
                                        "copied_ad_id": "120200000000010"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Foreign object",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This object does not belong to an Ad Account on this workspace."
                                }
                            }
                        }
                    },
                    {
                        "description": "Reconnect needed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "adId",
                        "in": "path",
                        "required": true,
                        "description": "Facebook ad id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsDuplicateRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/ad-accounts/{actId}/creatives": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "List creatives",
                "description": "Existing creatives on the ad account (for Create ad).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Creatives",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "creatives": [
                                        {
                                            "id": "120200000000003",
                                            "name": "Spring creative",
                                            "title": "Get a quote",
                                            "body": "Free quote",
                                            "thumbnail_url": "https://img",
                                            "object_type": "SHARE",
                                            "status": "ACTIVE"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected / ad account not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Ad Account not found for this workspace. Refresh Ad Accounts and try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Reconnect needed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "requires_reconnect": true,
                                    "message": "Facebook rejected the request - reconnect Facebook in Settings to grant the Ads permissions."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "actId",
                        "in": "path",
                        "required": true,
                        "description": "Graph ad account id including the act_ prefix (e.g. act_123456789)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Create creative",
                "description": "Builds a creative that runs as one of the connection's Pages from an uploaded image hash or video id, optionally with an Instant Form. With lead_gen_form_id the link is forced to https://fb.me/ (a Facebook rule). Upload files first with POST /media.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "creative": {
                                        "id": "120200000000003"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected / ad account not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Ad Account not found for this workspace. Refresh Ad Accounts and try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation, unknown Page/form, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "That Lead Form does not belong to the selected Page."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "actId",
                        "in": "path",
                        "required": true,
                        "description": "Graph ad account id including the act_ prefix (e.g. act_123456789)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsCreateCreativeRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/ad-accounts/{actId}/media": {
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Upload image or video",
                "description": "Multipart upload into the ad account library. Images return a `hash`, videos a `video_id`; both feed POST /creatives. jpg/jpeg/png up to 8 MB, mp4/mov up to 100 MB.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "actId",
                        "in": "path",
                        "required": true,
                        "description": "Graph ad account id including the act_ prefix (e.g. act_123456789)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsMediaUploadRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Uploaded",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "type": "image",
                                    "hash": "abc123hash",
                                    "url": "https://scontent.example/abc.png"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not connected / ad account not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Ad Account not found for this workspace. Refresh Ad Accounts and try again."
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid or empty file, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Images must be 8 MB or smaller."
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated"
                    }
                }
            }
        },
        "/api/marketing/meta-ads/ad-accounts/{actId}/insights": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Insights",
                "description": "Reporting at account, campaign, ad set or ad level, optionally split by a breakdown. Rows carry impressions, reach, frequency, clicks, spend, ctr, cpc, cpm, plus derived `leads` and `cost_per_lead` only when Meta returned a lead action (never invented).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Insights",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "level": "adset",
                                    "breakdown": "age",
                                    "currency": "USD",
                                    "insights": [
                                        {
                                            "adset_name": "US 25-55",
                                            "age": "25-34",
                                            "impressions": "1000",
                                            "reach": "800",
                                            "frequency": "1.25",
                                            "clicks": "40",
                                            "spend": "20.00",
                                            "ctr": "4.0",
                                            "cpc": "0.50",
                                            "cpm": "20.00",
                                            "leads": 4,
                                            "cost_per_lead": 5
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Not connected / ad account not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Ad Account not found for this workspace. Refresh Ad Accounts and try again."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid level/breakdown, or reconnect",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Invalid level."
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Could not complete the request on Facebook. Please try again shortly."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Meta-Connection",
                        "in": "header",
                        "required": false,
                        "description": "Which Facebook connection to act on (value from GET /api/marketing/meta-ads/connections). Omit for the first active one. An invalid or foreign value returns \"not connected\", never another account.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "actId",
                        "in": "path",
                        "required": true,
                        "description": "Graph ad account id including the act_ prefix (e.g. act_123456789)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "level",
                        "in": "query",
                        "required": false,
                        "description": "Report level (default account)",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "account",
                                "campaign",
                                "adset",
                                "ad"
                            ]
                        }
                    },
                    {
                        "name": "breakdown",
                        "in": "query",
                        "required": false,
                        "description": "Optional split of each row",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "age",
                                "gender",
                                "placement",
                                "device",
                                "region"
                            ]
                        }
                    },
                    {
                        "name": "date_preset",
                        "in": "query",
                        "required": false,
                        "description": "Preset window (default last_30d). Ignored when since and until are both sent",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "today",
                                "yesterday",
                                "last_7d",
                                "last_14d",
                                "last_30d",
                                "last_90d",
                                "this_month",
                                "last_month",
                                "maximum"
                            ]
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "description": "Start date Y-m-d (use with until)",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "until",
                        "in": "query",
                        "required": false,
                        "description": "End date Y-m-d (use with since)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/conversions/pixels": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Pixels to pick from",
                "description": "The Pixels on the ad accounts the connected Facebook account can reach. Save one with POST /api/marketing/meta-ads/conversions (pixel_id). No token is needed: events go through the connected Facebook account.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "List",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "connected": true,
                                    "pixels": [
                                        {
                                            "pixel_id": "123456789012345",
                                            "name": "Website Pixel",
                                            "ad_account": "Main ad account"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Facebook not connected",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "connected": false,
                                    "pixels": [],
                                    "message": "Connect Facebook first (the Connect button at the top of this page)."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/conversions": {
            "get": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "List Pixel / CAPI destinations",
                "description": "Labeled Pixel destinations for this company. Independent of Facebook OAuth. Tokens are never returned; only token_set and token_last4. An empty list means no events are sent. Ready Pixels receive Lead (new leads) and Schedule (bookings) automatically. A workflow send_meta_conversion step picks one of these for Lead, Schedule, Purchase or a custom stage.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "List",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "conversions": [
                                        {
                                            "id": 3,
                                            "name": "Main Pixel",
                                            "pixel_id": "123456789012345",
                                            "ready": true,
                                            "token_set": true,
                                            "token_last4": "89ab",
                                            "via": "token"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            },
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Create a Pixel / CAPI destination",
                "description": "Save a labeled Pixel ID. No token is needed: events send through the connected Facebook account (via=facebook). A pasted CAPI token is optional and takes priority (via=token).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "id": 3,
                                    "name": "Main Pixel",
                                    "pixel_id": "123456789012345",
                                    "ready": true,
                                    "token_set": true,
                                    "token_last4": "89ab",
                                    "via": "token",
                                    "success": true,
                                    "message": "Conversion saved. Leads, bookings and workflow steps now send events to this Pixel."
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "The name field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsConversionSettingsRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/meta-ads/conversions/{id}": {
            "put": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Update a Pixel / CAPI destination",
                "description": "Update the label, Pixel ID, and optional CAPI token. An empty token field keeps the existing token.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "id": 3,
                                    "name": "Main Pixel",
                                    "pixel_id": "123456789012345",
                                    "ready": true,
                                    "token_set": true,
                                    "token_last4": "89ab",
                                    "via": "token",
                                    "success": true,
                                    "message": "Conversion updated."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Conversion not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Conversion id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsConversionSettingsRequest"
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Remove a Pixel / CAPI destination",
                "description": "Deletes this labeled Pixel. Workflows that picked it will stop sending to it.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Removed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Conversion removed."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Conversion not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Conversion id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/marketing/meta-ads/conversions/{id}/test": {
            "post": {
                "tags": [
                    "Meta Ads"
                ],
                "summary": "Send a test CAPI event",
                "description": "Posts one event to this Pixel immediately (not queued). test_event_code is required so the test never counts as a real conversion. event_name may be Lead, Schedule, Purchase or a custom stage (e.g. Qualified). Purchase sends value (default 1) and currency (default USD).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Sent",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Meta received the test event. It shows under Events Manager \u2192 Test events.",
                                    "event_id": "test:12:3:abcd1234",
                                    "events_received": 1,
                                    "fbtrace_id": "TRACE123"
                                }
                            }
                        }
                    },
                    {
                        "description": "Not ready or Meta rejected",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Save a Pixel ID and CAPI access token on this conversion first."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Conversion id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/MetaAdsConversionTestRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/lead-forms/helpers": {
            "get": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "Lead Form helpers",
                "description": "PowerLists and contact columns for create/update. default_mode is the first-look mapping (phone + first name required). Not ads Lead Forms.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Helpers",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "powerlists": [
                                        {
                                            "id": 12,
                                            "name": "Inbound leads"
                                        }
                                    ],
                                    "fields": [
                                        {
                                            "key": "phone_number",
                                            "label": "Phone",
                                            "locked": true,
                                            "default_mode": "required"
                                        },
                                        {
                                            "key": "first_name",
                                            "label": "First Name",
                                            "locked": false,
                                            "default_mode": "required"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/marketing/lead-forms": {
            "get": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "List Lead Forms",
                "description": "Company Marketing Lead Forms. List rows omit js_snippet, curl, and secret_plain.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "List",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "lead_forms": [
                                        {
                                            "id": 8,
                                            "name": "Website form",
                                            "status": "Active",
                                            "powerlist_id": 12,
                                            "powerlist_name": "Inbound leads",
                                            "hits": 3,
                                            "public_id": "lf_abc123",
                                            "public_url": "https://example.com/lead-form/lf_abc123",
                                            "public_key": "pk_live_xxx",
                                            "secret_key_prefix": "sk_live_abcd",
                                            "created_at": "2026-10-02 11:00"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            },
            "post": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "Create Lead Form",
                "description": "Creates a Lead Form with a hosted URL, public key, and one-time secret_plain. Copy secret_plain now; it is not stored in plain text. Does not fire contact_created. Public ingest is POST /ingest/lead with the form key, not this Passport token.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Lead Form created. Copy secret_plain now; it will not be shown again.",
                                    "lead_form": {
                                        "id": 8,
                                        "name": "Website form",
                                        "status": "Active",
                                        "powerlist_id": 12,
                                        "powerlist_name": "Inbound leads",
                                        "hits": 3,
                                        "public_id": "lf_abc123",
                                        "public_url": "https://example.com/lead-form/lf_abc123",
                                        "public_key": "pk_live_xxx",
                                        "secret_key_prefix": "sk_live_abcd",
                                        "created_at": "2026-10-02 11:00",
                                        "fields": {
                                            "phone_number": "required",
                                            "first_name": "required",
                                            "last_name": "optional",
                                            "email": "optional"
                                        },
                                        "allowed_domains": [
                                            "example.com"
                                        ],
                                        "js_snippet": "<script>\u2026</script>",
                                        "curl": "curl -X POST \"https://example.com/ingest/lead\" \u2026",
                                        "secret_plain": "sk_live_NEW"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "The name field is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/LeadFormUpsertRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/lead-forms/{id}": {
            "get": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "Get Lead Form",
                "description": "Detail includes fields, allowed_domains, js_snippet, and curl. secret_plain is null except after create or regenerate.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Lead Form",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "lead_form": {
                                        "id": 8,
                                        "name": "Website form",
                                        "status": "Active",
                                        "powerlist_id": 12,
                                        "powerlist_name": "Inbound leads",
                                        "hits": 3,
                                        "public_id": "lf_abc123",
                                        "public_url": "https://example.com/lead-form/lf_abc123",
                                        "public_key": "pk_live_xxx",
                                        "secret_key_prefix": "sk_live_abcd",
                                        "created_at": "2026-10-02 11:00",
                                        "fields": {
                                            "phone_number": "required",
                                            "first_name": "required",
                                            "last_name": "optional",
                                            "email": "optional"
                                        },
                                        "allowed_domains": [
                                            "example.com"
                                        ],
                                        "js_snippet": "<script>\u2026</script>",
                                        "curl": "curl -X POST \"https://example.com/ingest/lead\" \u2026",
                                        "secret_plain": null
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Lead Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Lead Form id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            },
            "put": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "Update Lead Form",
                "description": "Does not rotate keys. Phone stays required.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Lead Form updated.",
                                    "lead_form": {
                                        "id": 8,
                                        "name": "Website form",
                                        "status": "Active",
                                        "powerlist_id": 12,
                                        "powerlist_name": "Inbound leads",
                                        "hits": 3,
                                        "public_id": "lf_abc123",
                                        "public_url": "https://example.com/lead-form/lf_abc123",
                                        "public_key": "pk_live_xxx",
                                        "secret_key_prefix": "sk_live_abcd",
                                        "created_at": "2026-10-02 11:00",
                                        "fields": {
                                            "phone_number": "required",
                                            "first_name": "required",
                                            "last_name": "optional",
                                            "email": "optional"
                                        },
                                        "allowed_domains": [
                                            "example.com"
                                        ],
                                        "js_snippet": "<script>\u2026</script>",
                                        "curl": "curl -X POST \"https://example.com/ingest/lead\" \u2026",
                                        "secret_plain": null
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Lead Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Select a PowerList from this account."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Lead Form id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/LeadFormUpsertRequest"
                            }
                        }
                    }
                }
            },
            "patch": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "Update Lead Form (PATCH)",
                "description": "Same as PUT /api/marketing/lead-forms/{id}.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Lead Form updated.",
                                    "lead_form": {
                                        "id": 8,
                                        "name": "Website form",
                                        "status": "Active",
                                        "powerlist_id": 12,
                                        "powerlist_name": "Inbound leads",
                                        "hits": 3,
                                        "public_id": "lf_abc123",
                                        "public_url": "https://example.com/lead-form/lf_abc123",
                                        "public_key": "pk_live_xxx",
                                        "secret_key_prefix": "sk_live_abcd",
                                        "created_at": "2026-10-02 11:00",
                                        "fields": {
                                            "phone_number": "required",
                                            "first_name": "required",
                                            "last_name": "optional",
                                            "email": "optional"
                                        },
                                        "allowed_domains": [
                                            "example.com"
                                        ],
                                        "js_snippet": "<script>\u2026</script>",
                                        "curl": "curl -X POST \"https://example.com/ingest/lead\" \u2026",
                                        "secret_plain": null
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Lead Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Lead Form id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/LeadFormUpsertRequest"
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "Delete Lead Form",
                "description": "Deletes the form and its keys. Existing contacts stay in the PowerList.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Lead Form deleted."
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Lead Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Lead Form id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/marketing/lead-forms/{id}/toggle-status": {
            "post": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "Toggle Lead Form status",
                "description": "Active \u2194 Inactive. Inactive forms reject hosted, JS, and cURL submits.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Toggled",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Lead Form deactivated.",
                                    "lead_form": {
                                        "id": 8,
                                        "name": "Website form",
                                        "status": "Inactive",
                                        "powerlist_id": 12,
                                        "powerlist_name": "Inbound leads",
                                        "hits": 3,
                                        "public_id": "lf_abc123",
                                        "public_url": "https://example.com/lead-form/lf_abc123",
                                        "public_key": "pk_live_xxx",
                                        "secret_key_prefix": "sk_live_abcd",
                                        "created_at": "2026-10-02 11:00",
                                        "fields": {
                                            "phone_number": "required",
                                            "first_name": "required",
                                            "last_name": "optional",
                                            "email": "optional"
                                        },
                                        "allowed_domains": [
                                            "example.com"
                                        ],
                                        "js_snippet": "<script>\u2026</script>",
                                        "curl": "curl -X POST \"https://example.com/ingest/lead\" \u2026",
                                        "secret_plain": null
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Lead Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Lead Form id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/api/marketing/lead-forms/{id}/regenerate-secret": {
            "post": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "Regenerate Lead Form secret",
                "description": "Issues a new sk_live_ key. The previous secret stops working immediately. Copy secret_plain now.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Regenerated",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "New API key generated. Copy secret_plain now; it will not be shown again.",
                                    "lead_form": {
                                        "id": 8,
                                        "name": "Website form",
                                        "status": "Active",
                                        "powerlist_id": 12,
                                        "powerlist_name": "Inbound leads",
                                        "hits": 3,
                                        "public_id": "lf_abc123",
                                        "public_url": "https://example.com/lead-form/lf_abc123",
                                        "public_key": "pk_live_xxx",
                                        "secret_key_prefix": "sk_live_abcd",
                                        "created_at": "2026-10-02 11:00",
                                        "fields": {
                                            "phone_number": "required",
                                            "first_name": "required",
                                            "last_name": "optional",
                                            "email": "optional"
                                        },
                                        "allowed_domains": [
                                            "example.com"
                                        ],
                                        "js_snippet": "<script>\u2026</script>",
                                        "curl": "curl -X POST \"https://example.com/ingest/lead\" \u2026",
                                        "secret_plain": "sk_live_NEW"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Lead Form not found."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Lead Form id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ]
            }
        },
        "/ingest/lead": {
            "post": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "Ingest lead (public)",
                "description": "Unauthenticated except by the Lead Form key. Use X-Lead-Key: pk_\u2026 (JS) or Authorization: Bearer sk_live_\u2026 (cURL). Do not send a Passport login token. Phone upserts the Contact into the form PowerList and fires the Lead Form workflow trigger (not contact_created).",
                "security": [],
                "responses": [
                    {
                        "description": "Accepted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "success",
                                    "action": "created"
                                }
                            }
                        }
                    },
                    {
                        "description": "Invalid key",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "message": "Invalid Lead Form key."
                                }
                            }
                        }
                    },
                    {
                        "description": "Inactive",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "message": "This Lead Form is inactive."
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "error",
                                    "message": "A valid phone number is required."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "X-Lead-Key",
                        "in": "header",
                        "required": false,
                        "description": "Public key pk_\u2026 for JS embed.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "Authorization",
                        "in": "header",
                        "required": false,
                        "description": "Bearer sk_live_\u2026 form secret for server-to-server cURL. Not a Passport token.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/LeadFormIngestRequest"
                            }
                        }
                    }
                }
            },
            "options": {
                "tags": [
                    "Lead Form"
                ],
                "summary": "Ingest lead CORS preflight",
                "description": "CORS preflight for JS embed. Returns 204.",
                "security": [],
                "responses": [
                    {
                        "description": "No content"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/carrier/application": {
            "get": {
                "tags": [
                    "Carrier"
                ],
                "summary": "Get carrier application",
                "description": "Current application for this company. company lists only profile values the carrier can use. An empty company field must be sent on submit. submitted is false until a reference exists. needs and request_message are set when status is info_requested. The partner key is not returned.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Application",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "submitted": false,
                                    "can_send": true,
                                    "company_ready": true,
                                    "company": {
                                        "legal_name": "Company Dev",
                                        "ein": "123456789",
                                        "entity": "LLC",
                                        "street": "100 Main Street",
                                        "city": "Austin",
                                        "state": "TX",
                                        "zip": "78701",
                                        "website": "https://companydev.test"
                                    },
                                    "reference": null,
                                    "status": null,
                                    "status_label": null,
                                    "needs": [],
                                    "request_message": null,
                                    "document_kinds": {
                                        "id": "Driver's license",
                                        "incorp": "Proof of incorporation",
                                        "consent": "Consent screenshots",
                                        "ein": "IRS EIN letter",
                                        "other": "Other document"
                                    },
                                    "preview": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            },
            "post": {
                "tags": [
                    "Carrier"
                ],
                "summary": "Submit carrier application",
                "description": "Submit once. Company or Admin only. Refused with 422 when a reference already exists, a required field is missing or invalid, or the carrier approval checklist (GET /api/carrier/application/readiness) is not all green; then readiness and missing list what to fix. Needs id_name (name on the ID) and signer_is_owner=1. Send company fields that GET left empty. multipart/form-data.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Submitted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Application submitted.",
                                    "reference": "34A7B785"
                                }
                            }
                        }
                    },
                    {
                        "description": "Not an owner or admin",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Only the account owner or an admin can submit this application."
                                }
                            }
                        }
                    },
                    {
                        "description": "Already submitted, profile incomplete, or validation failed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "This application is already submitted."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/CarrierApplicationSubmitRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/carrier/application/readiness": {
            "get": {
                "tags": [
                    "Carrier"
                ],
                "summary": "Carrier approval checklist",
                "description": "Carrier approval checklist. Nothing is sent. Items: business_email (no free email for company, signer or traceback email), email_matches_website (warn only, when a website is given), two_phones (business phone main_phone and the owner's direct cell signer_phone, different), owner_mobile (signer_phone must be a real cell line, not VoIP or landline; unchecked when the line check could not run), signer_confirmed (signer_is_owner), id_name_matches (id_name vs signer_name), id_document, required_fields. status is pass, fail, warn or unchecked. ready is true only with no fail and no unchecked; submitting is refused otherwise. Starts from the business profile; send any application field to check it. Send id_document_attached=1 when the file is ready but not uploaded yet. Max 30 per minute.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Checklist",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "submitted": false,
                                    "readiness": {
                                        "ready": false,
                                        "summary": "1 thing to fix before you can submit.",
                                        "items": [
                                            {
                                                "key": "business_email",
                                                "title": "Business email on your own domain",
                                                "status": "fail",
                                                "fix": "The company email is on gmail.com. The carrier declines free email addresses. Use an email on your business's own domain, like you@yourbusiness.com. You can set one up in about 10 minutes.",
                                                "help_url": "https://docs.aisync.link/carrier/get-a-business-email"
                                            },
                                            {
                                                "key": "owner_mobile",
                                                "title": "Owner's direct number is a cell phone",
                                                "status": "pass",
                                                "fix": null,
                                                "help_url": "https://docs.aisync.link/carrier/approval-checklist",
                                                "detail": "Cell line on T-Mobile USA, Inc."
                                            }
                                        ],
                                        "missing": [
                                            "Business email on your own domain: The company email is on gmail.com. ..."
                                        ],
                                        "help_url": "https://docs.aisync.link/carrier/approval-checklist",
                                        "business_email_help_url": "https://docs.aisync.link/carrier/get-a-business-email"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            },
            "post": {
                "tags": [
                    "Carrier"
                ],
                "summary": "Check carrier application fields",
                "description": "Carrier approval checklist. Nothing is sent. Items: business_email (no free email for company, signer or traceback email), email_matches_website (warn only, when a website is given), two_phones (business phone main_phone and the owner's direct cell signer_phone, different), owner_mobile (signer_phone must be a real cell line, not VoIP or landline; unchecked when the line check could not run), signer_confirmed (signer_is_owner), id_name_matches (id_name vs signer_name), id_document, required_fields. status is pass, fail, warn or unchecked. ready is true only with no fail and no unchecked; submitting is refused otherwise. Starts from the business profile; send any application field to check it. Send id_document_attached=1 when the file is ready but not uploaded yet. Max 30 per minute.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Checklist",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "submitted": false,
                                    "readiness": {
                                        "ready": false,
                                        "summary": "1 thing to fix before you can submit.",
                                        "items": [
                                            {
                                                "key": "business_email",
                                                "title": "Business email on your own domain",
                                                "status": "fail",
                                                "fix": "The company email is on gmail.com. The carrier declines free email addresses. Use an email on your business's own domain, like you@yourbusiness.com. You can set one up in about 10 minutes.",
                                                "help_url": "https://docs.aisync.link/carrier/get-a-business-email"
                                            },
                                            {
                                                "key": "owner_mobile",
                                                "title": "Owner's direct number is a cell phone",
                                                "status": "pass",
                                                "fix": null,
                                                "help_url": "https://docs.aisync.link/carrier/approval-checklist",
                                                "detail": "Cell line on T-Mobile USA, Inc."
                                            }
                                        ],
                                        "missing": [
                                            "Business email on your own domain: The company email is on gmail.com. ..."
                                        ],
                                        "help_url": "https://docs.aisync.link/carrier/approval-checklist",
                                        "business_email_help_url": "https://docs.aisync.link/carrier/get-a-business-email"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/carrier/application/files": {
            "post": {
                "tags": [
                    "Carrier"
                ],
                "summary": "Send requested carrier files",
                "description": "Only when GET status is info_requested. Company or Admin only. Upload the kinds listed in needs, on the same reference. Field names are file_id, file_incorp, file_consent, file_ein, and file_other. multipart/form-data.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Files sent",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Files sent. The carrier has the application again.",
                                    "application_status": "new"
                                }
                            }
                        }
                    },
                    {
                        "description": "Not an owner or admin",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Only the account owner or an admin can send these files."
                                }
                            }
                        }
                    },
                    {
                        "description": "Nothing to send, or a file is missing, too large, or the wrong type",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "There is nothing to send right now."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/CarrierApplicationFilesRequest"
                            }
                        }
                    }
                }
            }
        },
        "/api/texting-registration": {
            "get": {
                "tags": [
                    "Texting registration"
                ],
                "summary": "Get texting registration",
                "description": "Details, the last compliance check, and the pipeline (stages with state done, current, upcoming or attention, usual time per stage, and an expected live date range once submitted).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Registration",
                        "content": {
                            "application/json": {
                                "example": {
                                    "registration": {
                                        "status": "ready",
                                        "business": {
                                            "legal_name": "Sunrise Dental LLC",
                                            "website": "https://sunrisedental.com"
                                        },
                                        "ein": "**-***4567",
                                        "campaign": {
                                            "use_case": "MIXED"
                                        },
                                        "can_edit": true
                                    },
                                    "check": {
                                        "ready": true,
                                        "on_hold": false,
                                        "counts": {
                                            "pass": 27,
                                            "warn": 1,
                                            "fail": 0
                                        },
                                        "checks": [
                                            {
                                                "section": "website",
                                                "key": "privacy_sms",
                                                "status": "pass",
                                                "title": "Privacy Policy protects mobile numbers",
                                                "fix": null,
                                                "copy": null
                                            }
                                        ]
                                    },
                                    "pipeline": {
                                        "status": "ready",
                                        "headline": "Everything checks out. You're ready to submit.",
                                        "next_step": "Submit your registration. Nothing is sent until you do.",
                                        "expected_live": null,
                                        "stages": [
                                            {
                                                "key": "check",
                                                "label": "Compliance check",
                                                "state": "done",
                                                "usual_time": "Instant"
                                            },
                                            {
                                                "key": "submitted",
                                                "label": "Submitted",
                                                "state": "upcoming",
                                                "usual_time": "Same day"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            },
            "put": {
                "tags": [
                    "Texting registration"
                ],
                "summary": "Save texting registration details",
                "description": "Save business details, EIN and campaign details. Owners and admins only. Changing details after a passing check sets it back to draft. Refused with 409 once submitted (until a change is requested).",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Saved. Run the compliance check when you are ready.",
                                    "registration": {
                                        "status": "ready",
                                        "business": {
                                            "legal_name": "Sunrise Dental LLC",
                                            "website": "https://sunrisedental.com"
                                        },
                                        "ein": "**-***4567",
                                        "campaign": {
                                            "use_case": "MIXED"
                                        },
                                        "can_edit": true
                                    },
                                    "check": {
                                        "ready": true,
                                        "on_hold": false,
                                        "counts": {
                                            "pass": 27,
                                            "warn": 1,
                                            "fail": 0
                                        },
                                        "checks": [
                                            {
                                                "section": "website",
                                                "key": "privacy_sms",
                                                "status": "pass",
                                                "title": "Privacy Policy protects mobile numbers",
                                                "fix": null,
                                                "copy": null
                                            }
                                        ]
                                    },
                                    "pipeline": {
                                        "status": "ready",
                                        "headline": "Everything checks out. You're ready to submit.",
                                        "next_step": "Submit your registration. Nothing is sent until you do.",
                                        "expected_live": null,
                                        "stages": [
                                            {
                                                "key": "check",
                                                "label": "Compliance check",
                                                "state": "done",
                                                "usual_time": "Instant"
                                            },
                                            {
                                                "key": "submitted",
                                                "label": "Submitted",
                                                "state": "upcoming",
                                                "usual_time": "Same day"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not an owner or admin",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Only the account owner or an admin can change the texting registration."
                                }
                            }
                        }
                    },
                    {
                        "description": "Already submitted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Your registration is already submitted. Details can be changed only if the carriers ask for a change."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "business": {
                                        "type": "object",
                                        "description": "Any of: legal_name, dba, entity_type (PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT, SOLE_PROPRIETOR), vertical, street, street2, city, state, zip, website, email, phone, contact_first_name, contact_last_name, contact_phone, contact_title, stock_symbol, stock_exchange. Partial updates are fine; empty fields are pre-filled from the business profile."
                                    },
                                    "ein": {
                                        "type": "string",
                                        "example": "74-1234567",
                                        "description": "9-digit EIN. Stored encrypted; only the last 4 digits are ever returned."
                                    },
                                    "campaign": {
                                        "type": "object",
                                        "description": "Any of: use_case (MARKETING, MIXED, CUSTOMER_CARE, ACCOUNT_NOTIFICATION, LOW_VOLUME), sub_use_cases (2+ for MIXED), description, opt_in_method (website_form, lead_form, verbal, paper, keyword), opt_in_description, opt_in_consent_text, opt_in_url, opt_in_proof_url, privacy_url, terms_url, samples (2 to 5), age_gated, attest_consent, attest_accurate."
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/texting-registration/check": {
            "post": {
                "tags": [
                    "Texting registration"
                ],
                "summary": "Run the compliance check",
                "description": "Visits the website (home, privacy, terms, opt-in form, embedded form widgets) and checks the business, website, consent and messages. Each failed item has fix (what to do) and copy (exact text to paste). Optional body saves details first. Max 10 per minute.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Checked",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Everything checks out. You can submit.",
                                    "registration": {
                                        "status": "ready",
                                        "business": {
                                            "legal_name": "Sunrise Dental LLC",
                                            "website": "https://sunrisedental.com"
                                        },
                                        "ein": "**-***4567",
                                        "campaign": {
                                            "use_case": "MIXED"
                                        },
                                        "can_edit": true
                                    },
                                    "check": {
                                        "ready": true,
                                        "on_hold": false,
                                        "counts": {
                                            "pass": 27,
                                            "warn": 1,
                                            "fail": 0
                                        },
                                        "checks": [
                                            {
                                                "section": "website",
                                                "key": "privacy_sms",
                                                "status": "pass",
                                                "title": "Privacy Policy protects mobile numbers",
                                                "fix": null,
                                                "copy": null
                                            }
                                        ]
                                    },
                                    "pipeline": {
                                        "status": "ready",
                                        "headline": "Everything checks out. You're ready to submit.",
                                        "next_step": "Submit your registration. Nothing is sent until you do.",
                                        "expected_live": null,
                                        "stages": [
                                            {
                                                "key": "check",
                                                "label": "Compliance check",
                                                "state": "done",
                                                "usual_time": "Instant"
                                            },
                                            {
                                                "key": "submitted",
                                                "label": "Submitted",
                                                "state": "upcoming",
                                                "usual_time": "Same day"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not an owner or admin"
                    },
                    {
                        "description": "No details yet",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "Add your business details first."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "business": {
                                        "type": "object",
                                        "description": "Any of: legal_name, dba, entity_type (PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT, SOLE_PROPRIETOR), vertical, street, street2, city, state, zip, website, email, phone, contact_first_name, contact_last_name, contact_phone, contact_title, stock_symbol, stock_exchange. Partial updates are fine; empty fields are pre-filled from the business profile."
                                    },
                                    "ein": {
                                        "type": "string",
                                        "example": "74-1234567",
                                        "description": "9-digit EIN. Stored encrypted; only the last 4 digits are ever returned."
                                    },
                                    "campaign": {
                                        "type": "object",
                                        "description": "Any of: use_case (MARKETING, MIXED, CUSTOMER_CARE, ACCOUNT_NOTIFICATION, LOW_VOLUME), sub_use_cases (2+ for MIXED), description, opt_in_method (website_form, lead_form, verbal, paper, keyword), opt_in_description, opt_in_consent_text, opt_in_url, opt_in_proof_url, privacy_url, terms_url, samples (2 to 5), age_gated, attest_consent, attest_accurate."
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/texting-registration/fix-copy": {
            "get": {
                "tags": [
                    "Texting registration"
                ],
                "summary": "Get ready-to-paste compliance wording",
                "description": "Privacy clause, SMS terms, opt-in checkbox text, opt-in description, sample messages and HELP / STOP / START replies, filled in with the business name.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Copy",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "brand": "Sunrise Dental",
                                    "copy": {
                                        "privacy_clause": "SMS/Text messaging: No mobile information will be shared with third parties or affiliates for marketing or promotional purposes...",
                                        "sample_messages": [
                                            "Hi [First Name], this is [Agent] from Sunrise Dental..."
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/texting-registration/submit": {
            "post": {
                "tags": [
                    "Texting registration"
                ],
                "summary": "Submit texting registration",
                "description": "Re-runs the full compliance check on the server and submits only if it passes. Owners and admins only. Max 5 per minute.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Submitted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "You're submitted! We'll keep you posted at every step.",
                                    "registration": {
                                        "status": "ready",
                                        "business": {
                                            "legal_name": "Sunrise Dental LLC",
                                            "website": "https://sunrisedental.com"
                                        },
                                        "ein": "**-***4567",
                                        "campaign": {
                                            "use_case": "MIXED"
                                        },
                                        "can_edit": true
                                    },
                                    "check": {
                                        "ready": true,
                                        "on_hold": false,
                                        "counts": {
                                            "pass": 27,
                                            "warn": 1,
                                            "fail": 0
                                        },
                                        "checks": [
                                            {
                                                "section": "website",
                                                "key": "privacy_sms",
                                                "status": "pass",
                                                "title": "Privacy Policy protects mobile numbers",
                                                "fix": null,
                                                "copy": null
                                            }
                                        ]
                                    },
                                    "pipeline": {
                                        "status": "ready",
                                        "headline": "Everything checks out. You're ready to submit.",
                                        "next_step": "Submit your registration. Nothing is sent until you do.",
                                        "expected_live": null,
                                        "stages": [
                                            {
                                                "key": "check",
                                                "label": "Compliance check",
                                                "state": "done",
                                                "usual_time": "Instant"
                                            },
                                            {
                                                "key": "submitted",
                                                "label": "Submitted",
                                                "state": "upcoming",
                                                "usual_time": "Same day"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not an owner or admin"
                    },
                    {
                        "description": "Check failed, on hold, or already submitted: nothing was sent",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "A few things need fixing before we can submit. Nothing was sent."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/marketing/google-ads/customers/{customerId}/media": {
            "post": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Upload image",
                "description": "Uploads a jpg, png, or webp (max 5 MB) as a Google image asset. Use resource_name as image_resource on the image-ad call. Google video ads are not on this surface.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Uploaded",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "type": "image",
                                    "id": "123",
                                    "resource_name": "customers/111/assets/123"
                                }
                            }
                        }
                    },
                    {
                        "description": "Missing or empty file",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The uploaded file is empty."
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The ad network rejected the request."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "customerId",
                        "in": "path",
                        "required": true,
                        "description": "Google Ads customer id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "file"
                                ],
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "Image or video file"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/google-ads/customers/{customerId}/image-ads": {
            "post": {
                "tags": [
                    "Google Ads"
                ],
                "summary": "Create image ad",
                "description": "Creates a Demand Gen image ad. Pass ad_group_id, or campaign_id to create the ad group first. image_resource comes from the upload. The ad is created inside the campaign; a paused campaign does not spend.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "ad": {
                                        "id": "55"
                                    },
                                    "ad_group": "customers/111/adGroups/9"
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation failed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The given data was invalid."
                                }
                            }
                        }
                    },
                    {
                        "description": "Google Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The ad network rejected the request."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "customerId",
                        "in": "path",
                        "required": true,
                        "description": "Google Ads customer id (digits)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "final_url",
                                    "image_resource",
                                    "headlines",
                                    "business_name"
                                ],
                                "properties": {
                                    "ad_group_id": {
                                        "type": "string",
                                        "description": "Ad group resource name or numeric id. Required when campaign_id is omitted."
                                    },
                                    "campaign_id": {
                                        "type": "string",
                                        "description": "Creates the ad group on this campaign when ad_group_id is omitted."
                                    },
                                    "ad_group_name": {
                                        "type": "string"
                                    },
                                    "final_url": {
                                        "type": "string"
                                    },
                                    "image_resource": {
                                        "type": "string"
                                    },
                                    "headlines": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "descriptions": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "business_name": {
                                        "type": "string",
                                        "maxLength": 25
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/tiktok-ads/advertisers/{advertiserId}/media": {
            "post": {
                "tags": [
                    "TikTok Ads"
                ],
                "summary": "Upload image or video",
                "description": "Uploads jpg, png, webp, mp4, or mov (max 50 MB). Put image_id or video_id on the existing create-ad creatives array. TikTok still needs an identity on that ad.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Uploaded",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "type": "image",
                                    "image_id": "ad-site-1"
                                }
                            }
                        }
                    },
                    {
                        "description": "Missing or empty file",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The uploaded file is empty."
                                }
                            }
                        }
                    },
                    {
                        "description": "TikTok Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The ad network rejected the request."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "advertiserId",
                        "in": "path",
                        "required": true,
                        "description": "TikTok advertiser id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "file"
                                ],
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "Image or video file"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/snapchat-ads/ad-accounts/{adAccountId}/media": {
            "post": {
                "tags": [
                    "Snapchat Ads"
                ],
                "summary": "Upload image or video",
                "description": "Creates Snapchat media and uploads the file (jpg, png, webp, mp4, or mov, max 50 MB). Use media_id on the creative call.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Uploaded",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "type": "image",
                                    "media_id": "media-1"
                                }
                            }
                        }
                    },
                    {
                        "description": "Missing or empty file",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The uploaded file is empty."
                                }
                            }
                        }
                    },
                    {
                        "description": "Snapchat Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The ad network rejected the request."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "adAccountId",
                        "in": "path",
                        "required": true,
                        "description": "Snapchat ad account id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "file"
                                ],
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "Image or video file"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/snapchat-ads/ad-accounts/{adAccountId}/creatives": {
            "post": {
                "tags": [
                    "Snapchat Ads"
                ],
                "summary": "Create creative",
                "description": "WEB_VIEW creative. Attach it with the existing create-ad call (creative_id + ad_squad_id). The ad itself stays paused unless status is ACTIVE.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "creative": {
                                        "id": "creative-1"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation failed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The given data was invalid."
                                }
                            }
                        }
                    },
                    {
                        "description": "Snapchat Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The ad network rejected the request."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "adAccountId",
                        "in": "path",
                        "required": true,
                        "description": "Snapchat ad account id",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name",
                                    "headline",
                                    "brand_name",
                                    "url",
                                    "media_id",
                                    "profile_id"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "headline": {
                                        "type": "string",
                                        "maxLength": 34
                                    },
                                    "brand_name": {
                                        "type": "string",
                                        "maxLength": 32
                                    },
                                    "url": {
                                        "type": "string"
                                    },
                                    "media_id": {
                                        "type": "string"
                                    },
                                    "profile_id": {
                                        "type": "string",
                                        "description": "Public profile on this ad account"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/linkedin-ads/ad-accounts/{accountId}/media": {
            "post": {
                "tags": [
                    "LinkedIn Ads"
                ],
                "summary": "Upload image",
                "description": "Uploads a jpg or png (max 5 MB) owned by the ad account. LinkedIn video is not on this surface. Use image on the creative call.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Uploaded",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "type": "image",
                                    "image": "urn:li:image:1"
                                }
                            }
                        }
                    },
                    {
                        "description": "Missing or empty file",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The uploaded file is empty."
                                }
                            }
                        }
                    },
                    {
                        "description": "LinkedIn Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The ad network rejected the request."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "accountId",
                        "in": "path",
                        "required": true,
                        "description": "LinkedIn ad account id or URN",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "file"
                                ],
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "Image or video file"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/linkedin-ads/ad-accounts/{accountId}/creatives": {
            "post": {
                "tags": [
                    "LinkedIn Ads"
                ],
                "summary": "Create creative",
                "description": "Creates a post and a paused creative on the given campaign URN. organization_urn is the company page that authors the post.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "creative": {
                                        "id": "urn:li:sponsoredCreative:1"
                                    },
                                    "post": "urn:li:share:1"
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation failed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The given data was invalid."
                                }
                            }
                        }
                    },
                    {
                        "description": "LinkedIn Ads error",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": false,
                                    "message": "The ad network rejected the request."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "accountId",
                        "in": "path",
                        "required": true,
                        "description": "LinkedIn ad account id or URN",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "organization_urn",
                                    "campaign_urn",
                                    "commentary",
                                    "headline",
                                    "url",
                                    "image"
                                ],
                                "properties": {
                                    "organization_urn": {
                                        "type": "string"
                                    },
                                    "campaign_urn": {
                                        "type": "string"
                                    },
                                    "commentary": {
                                        "type": "string"
                                    },
                                    "headline": {
                                        "type": "string"
                                    },
                                    "url": {
                                        "type": "string"
                                    },
                                    "image": {
                                        "type": "string",
                                        "description": "Image URN from the upload"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/ads/summary": {
            "get": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Spend summary",
                "description": "Same numbers as the Ads Manager home chart. preset is 14, today, 7, 30, or custom (then since and until, max 90 days). Mixed currencies are not added together: spend is null and mixed is true.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Summary",
                        "content": {
                            "application/json": {
                                "example": {
                                    "spend": 12.5,
                                    "currency": "USD",
                                    "mixed": false,
                                    "campaigns": [
                                        {
                                            "id": "encrypted",
                                            "title": "Summer offer",
                                            "status": "active"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "preset",
                        "in": "query",
                        "required": false,
                        "description": "14, today, 7, 30, or custom",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "description": "Y-m-d when preset=custom",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "until",
                        "in": "query",
                        "required": false,
                        "description": "Y-m-d when preset=custom",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/ads/campaigns": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Create draft campaign",
                "description": "Creates a local draft named New campaign. Nothing is sent to an ad network until launch.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "id": "encrypted",
                                    "href": "/ads/campaigns/encrypted"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/marketing/ads/import": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Import network campaigns",
                "description": "Copies campaigns that already exist on connected accounts into Ads Manager. Does not create a new campaign on the network. One account failing does not stop the others.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Imported",
                        "content": {
                            "application/json": {
                                "example": {
                                    "imported": 1,
                                    "errors": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ]
            }
        },
        "/api/marketing/ads/campaigns/{campaign}": {
            "get": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Campaign detail",
                "description": "Groups, ads, connected accounts, and the launch review. Ad copy updates use the numeric ad id. Creative upload uses ad.key.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Campaign",
                        "content": {
                            "application/json": {
                                "example": {
                                    "campaign": {
                                        "id": "encrypted",
                                        "name": "Summer offer",
                                        "status": "draft"
                                    },
                                    "review": {
                                        "ready": false,
                                        "problems": []
                                    },
                                    "accounts": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Not found"
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Update campaign",
                "description": "Saves name, objective (leads, traffic, sales, engagement, awareness), daily budget, currency, destination URL, country codes, lead location, excluded accounts, and ad copy. A www URL is stored with https://. Changes on a live campaign are pushed to the networks that already have it.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "campaign": {
                                        "id": 1,
                                        "key": "encrypted",
                                        "status": "draft",
                                        "label": "Draft"
                                    },
                                    "review": {
                                        "ready": false,
                                        "problems": []
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation failed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "The given data was invalid."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "objective": {
                                        "type": "string"
                                    },
                                    "daily_budget": {
                                        "type": "number"
                                    },
                                    "currency": {
                                        "type": "string"
                                    },
                                    "destination_url": {
                                        "type": "string"
                                    },
                                    "locations": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "lead_location": {
                                        "type": "string"
                                    },
                                    "excluded_account_keys": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "platform:accountId rows to skip on launch"
                                    },
                                    "builder_settings": {
                                        "type": "object"
                                    },
                                    "ads": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "put": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Update campaign",
                "description": "Saves name, objective (leads, traffic, sales, engagement, awareness), daily budget, currency, destination URL, country codes, lead location, excluded accounts, and ad copy. A www URL is stored with https://. Changes on a live campaign are pushed to the networks that already have it.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "campaign": {
                                        "id": 1,
                                        "key": "encrypted",
                                        "status": "draft",
                                        "label": "Draft"
                                    },
                                    "review": {
                                        "ready": false,
                                        "problems": []
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Validation failed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "The given data was invalid."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "objective": {
                                        "type": "string"
                                    },
                                    "daily_budget": {
                                        "type": "number"
                                    },
                                    "currency": {
                                        "type": "string"
                                    },
                                    "destination_url": {
                                        "type": "string"
                                    },
                                    "locations": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "lead_location": {
                                        "type": "string"
                                    },
                                    "excluded_account_keys": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "platform:accountId rows to skip on launch"
                                    },
                                    "builder_settings": {
                                        "type": "object"
                                    },
                                    "ads": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/groups": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Add ad group",
                "description": "Adds a local ad group and its first ad.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "group": {
                                        "id": 2,
                                        "name": "Ad group 2"
                                    },
                                    "ad": {
                                        "id": 3,
                                        "key": "encrypted"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/ads": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Add ad",
                "description": "Adds an ad in the group. Omit group_id to use the first group.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "ad": {
                                        "id": 4,
                                        "key": "encrypted",
                                        "name": "Ad 2"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "group_id": {
                                        "type": "integer"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/ads/{ad}/duplicate": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Duplicate ad",
                "description": "Copies the ad (copy, call to action and creative) into the same ad group, named \"<name> copy\". Use it to make variations.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Copied",
                        "content": {
                            "application/json": {
                                "example": {
                                    "ad": {
                                        "id": 5,
                                        "key": "encrypted",
                                        "name": "Mini VSL copy"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "ad",
                        "in": "path",
                        "required": true,
                        "description": "Ad key from the campaign detail (ad.key)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/ads/{ad}": {
            "delete": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Delete ad",
                "description": "Deletes an ad and its creative. Draft campaigns only (pause a live campaign instead). An ad group keeps at least one ad.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "deleted": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Not allowed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "This campaign is live. Pause it instead of deleting ads."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "ad",
                        "in": "path",
                        "required": true,
                        "description": "Ad key from the campaign detail (ad.key)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/groups/{group}": {
            "patch": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Rename ad group",
                "description": "Renames a local ad group.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Renamed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "group": {
                                        "id": 2,
                                        "name": "Retargeting"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "group",
                        "in": "path",
                        "required": true,
                        "description": "Ad group id",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    }
                }
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/ads/{ad}/creative": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Upload creative",
                "description": "Stores the image or video on this ad (jpg, png, webp, gif, mp4, mov, max 50 MB). Launch sends it to each checked network.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Stored",
                        "content": {
                            "application/json": {
                                "example": {
                                    "creative": {
                                        "id": 1,
                                        "kind": "image",
                                        "url": "/storage/ads/1/file.webp"
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Missing file",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "The given data was invalid."
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "ad",
                        "in": "path",
                        "required": true,
                        "description": "Ad key from the campaign detail (ad.key)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "file"
                                ],
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "Image or video file"
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Remove creative",
                "description": "Deletes the stored file for this ad.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Removed",
                        "content": {
                            "application/json": {
                                "example": {
                                    "ok": true
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "ad",
                        "in": "path",
                        "required": true,
                        "description": "Ad key from the campaign detail (ad.key)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/identities": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "List TikTok and Snapchat identities",
                "description": "Pages and LinkedIn organizations are already on the campaign detail. This call asks TikTok and Snapchat for identities. Dummy tokens return an empty list.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Identities",
                        "content": {
                            "application/json": {
                                "example": {
                                    "tiktok": [],
                                    "snapchat": []
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/launch": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Launch",
                "description": "Sends the campaign to each checked connected account on its own. One account failing does not roll back the others. Returns 422 with the review when the campaign is not ready.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "campaign": {
                                        "id": 1,
                                        "key": "encrypted",
                                        "status": "draft",
                                        "label": "Draft"
                                    },
                                    "review": {
                                        "ready": false,
                                        "problems": []
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Not ready",
                        "content": {
                            "application/json": {
                                "example": {
                                    "message": "Ad 1 needs a headline.",
                                    "errors": [],
                                    "review": {
                                        "ready": false
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/pause": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Pause",
                "description": "Pauses every delivery that already has a network campaign. A draft that was never launched only changes locally.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "campaign": {
                                        "id": 1,
                                        "key": "encrypted",
                                        "status": "draft",
                                        "label": "Draft"
                                    },
                                    "review": {
                                        "ready": false,
                                        "problems": []
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/resume": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Resume",
                "description": "Resumes deliveries that already exist on a network.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Saved",
                        "content": {
                            "application/json": {
                                "example": {
                                    "campaign": {
                                        "id": 1,
                                        "key": "encrypted",
                                        "status": "draft",
                                        "label": "Draft"
                                    },
                                    "review": {
                                        "ready": false,
                                        "problems": []
                                    }
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/marketing/ads/campaigns/{campaign}/duplicate": {
            "post": {
                "tags": [
                    "Ads Manager"
                ],
                "summary": "Duplicate",
                "description": "Copies the campaign locally as a draft. Does not copy it onto the ad networks.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": [
                    {
                        "description": "Copied",
                        "content": {
                            "application/json": {
                                "example": {
                                    "id": "encrypted",
                                    "href": "/ads/campaigns/encrypted"
                                }
                            }
                        }
                    },
                    {
                        "description": "Unauthenticated"
                    }
                ],
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "path",
                        "required": true,
                        "description": "Encrypted campaign id from the summary or create response",
                        "schema": {
                            "type": "string"
                        }
                    }
                ]
            }
        },
        "/api/conversations/email/send": {
            "post": {
                "tags": [
                    "Conversations"
                ],
                "summary": "Send a new email or reply to one selected email",
                "description": "Sends to the contact email address. For a reply, pass the numeric log id of an Email belonging to this contact and account. Omit reply_to_log_id for a separate new email. Header identities are derived on the server, never accepted from the caller. If a historical email has no verified message identity, the reply is sent without invented threading headers and the response includes a warning. Existing email opt-out, permissions, sending defaults and request deduplication apply.",
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "contact_id",
                                    "subject",
                                    "body"
                                ],
                                "properties": {
                                    "contact_id": {
                                        "type": "integer",
                                        "minimum": 1
                                    },
                                    "subject": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "Preserved as entered; no line breaks or null characters."
                                    },
                                    "body": {
                                        "type": "string",
                                        "maxLength": 20000
                                    },
                                    "reply_to_log_id": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "nullable": true
                                    },
                                    "request_id": {
                                        "type": "string",
                                        "format": "uuid",
                                        "description": "Reuse the same UUID when retrying this send."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Accepted for sending; data includes log_id, contact_id, to, subject, reply_to_log_id, threading_available and nullable threading_warning. Acceptance does not confirm delivery."
                    },
                    "404": {
                        "description": "Contact not found."
                    },
                    "409": {
                        "description": "Request already processing or assigned to another contact."
                    },
                    "422": {
                        "description": "Invalid input, parent not an email in this contact conversation, invalid email address or email opt-out."
                    },
                    "502": {
                        "description": "Email could not be sent."
                    }
                }
            }
        }
    }
}