{ "openapi": "3.0.3", "info": { "title": "Rizzdial API", "description": "Rizzdial platform 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 \u00e2\u2020\u2019 only general_prompt is used, all section fields are ignored. sectioned \u00e2\u2020\u2019 general_prompt + any filled section fields are all concatenated together." }, "general_prompt": { "type": "string", "example": "You are a sales assistant...", "description": "Main project instructions (required in both modes)." }, "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 \u00e2\u2020\u2019 all section fields will be cleared to null. sectioned \u00e2\u2020\u2019 section fields you provide will be saved." }, "general_prompt": { "type": "string", "example": "You are a sales assistant...", "description": "Main project instructions" }, "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": { "mappings": { "type": "object", "description": "Key-value pairs of local contact field name \u00e2\u2020\u2019 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." } } }, "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\"." } } }, "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\u00e2\u20ac\u201c120 000 ms = 5 s\u00e2\u20ac\u201c2 min). Default is typically 30 000 ms (30 s)." } } }, "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", "Plivo" ], "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." } } }, "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": "30", "description": "Seconds to wait before hanging up an unanswered call. Allowed: 15, 20, 25, 30, 35, 40, 45, 50, 55, 60. Default: 30" }, "dial_at_a_time": { "type": "integer", "example": 1, "minimum": 1, "description": "Number of simultaneous outbound calls. Minimum: 1" }, "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": "Whether to ignore the Do-Not-Call list. Default: No" }, "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, "description": "Number of simultaneous outbound calls. Minimum: 1" }, "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": "Whether to ignore the Do-Not-Call list" }, "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 and openai_gpt. 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: or gpt. openai_gpt config: { prompt, provider?: openai|claude, model?, action_type? }.", "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" } } }, "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" }, { "name": "Google Ads", "description": "Marketing \u2192 Google Ads: customers, campaigns, ads, 7-day insights, Lead Forms. Same live Manager (REST v25). Connect/disconnect is not on this surface." }, { "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)" }, { "name": "Reports", "description": "Reports Call & SMS Reports" } ], "paths": { "/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.", "security": [ { "BearerAuth": [] } ], "responses": [ { "description": "Paginated agents" }, { "description": "Unauthenticated" } ], "parameters": [ { "name": "per_page", "in": "query", "required": false, "description": "Items per page (max 30, default 15)", "schema": { "type": "integer" } } ] } }, "/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 \u00e2\u20ac\u201d the new prompt is pushed live to the agent config and will be used on all future calls from that point forward. The created prompt is also stored in the agent's prompt history. Supports two modes controlled by prompt_mode \u00e2\u20ac\u201d \"single\": only general_prompt is used, all section fields are ignored. \"sectioned\": general_prompt plus any filled section fields are concatenated before being sent to the agent. Section fields that are left empty or null are skipped.", "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 \u00e2\u20ac\u201d any field you leave out stays unchanged. If prompt_mode is \"single\", all section fields are forced to null regardless of what you send. If prompt_mode is \"sectioned\", the section fields you provide will be saved. This does NOT push any changes to the live agent \u00e2\u20ac\u201d it only updates the saved history record. To activate a prompt on the agent, 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/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 or Plivo. 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 or Plivo)", "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/Plivo, 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/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/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 contact by its Base64 encoded ID. The disposition must belong to the authenticated company.", "security": [ { "BearerAuth": [] } ], "responses": [ { "description": "Disposition updated successfully", "content": { "application/json": { "example": { "status": "success", "msg": "Disposition updated successfully.", "data": { "contact_id": "MQ==", "disposition_id": "Mw==", "disposition": "Not Interested" } } } } }, { "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: " } } } }, { "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\": \"\" }` where `` 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/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: 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. 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:)", "config_fields": { "gpt_field": "Use condition field gpt: or gpt" }, "sort_order": 12 }, { "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 } ] } } } } }, { "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). 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" ] } } } } }, { "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}/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/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). `{id}` is the location row id from GET /api/settings/ghl/locations, or the LeadConnector locationId string. Does **not** connect or reconnect OAuth.", "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": "No create-ad on this surface. 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" } } } } } } } }