{"openapi":"3.1.0","info":{"title":"Sophiie API","version":"1.0.0","description":"REST API for Sophiie - a B2B SaaS platform for sales pipeline management. These endpoints provide access to leads, inquiries, and other core data with bearer token authentication.","contact":{"name":"Sophiie API Support","url":"https://sophiie.ai"}},"tags":[{"name":"Appointments"},{"name":"Calls"},{"name":"Companies"},{"name":"FAQs"},{"name":"Inquiries"},{"name":"Leads"},{"name":"Members"},{"name":"Organization"},{"name":"Policies"},{"name":"SMS"},{"name":"Scenarios"},{"name":"Transfers"}],"servers":[{"url":"https://api.sophiie.ai","description":"Production server"},{"url":"https://api.dev.sophiie.ai","description":"Development server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication for API access."}},"schemas":{},"parameters":{}},"paths":{"/v1/appointments":{"get":{"summary":"List Appointments","description":"Retrieve a paginated list of appointments (also referred to as Jobs). Optionally filter by lead ID. Returns appointment data including scheduling details, status, and associated lead information. Results are filtered by the organization associated with the API key.","tags":["Appointments"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filter appointments by lead ID","example":"ld_abc123"},"required":false,"description":"Filter appointments by lead ID","name":"leadId","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated appointment data","content":{"application/json":{"schema":{"type":"object","properties":{"appointments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the appointment","example":"apt_abc123"},"serialId":{"type":"number","description":"Sequential ID within the organization","example":42},"title":{"type":"string","description":"Title of the appointment","example":"Installation Consultation"},"description":{"type":"string","nullable":true,"description":"Description of the appointment","example":"Initial consultation for kitchen renovation"},"start":{"type":"string","description":"Start date and time (ISO 8601)","example":"2023-12-01T10:00:00.000Z"},"end":{"type":"string","description":"End date and time (ISO 8601)","example":"2023-12-01T11:00:00.000Z"},"status":{"type":"string","description":"Current status of the appointment","example":"PENDING"},"leadId":{"type":"string","description":"Associated lead ID","example":"ld_abc123"},"attendees":{"type":"array","items":{"type":"string"},"description":"Array of attendee email addresses","example":["john.doe@example.com"]},"tradeService":{"type":"object","nullable":true,"properties":{"id":{"type":"number"},"name":{"type":"string"}},"required":["id","name"],"description":"Associated service information","example":{"id":1,"name":"Plumbing"}},"notes":{"type":"string","nullable":true,"description":"Internal notes about the appointment","example":"Customer prefers morning appointments"},"customerNotes":{"type":"string","nullable":true,"description":"Notes from the customer","example":"Please call before arriving"},"isRescheduled":{"type":"boolean","description":"Whether this appointment has been rescheduled","example":false},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","serialId","title","description","start","end","status","leadId","attendees","tradeService","notes","customerNotes","isRescheduled","createdAt"]},"description":"Array of appointments (also referred to as Jobs in some contexts)"},"totalPages":{"type":"number","description":"Total number of pages available","example":3},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of appointments","example":28}},"required":["appointments","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/calls":{"post":{"summary":"Send Call","description":"Initiate a call to a phone number. The call will be made using the organization's virtual assistant associated with the API key.","tags":["Calls"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the person to call","example":"John Doe"},"phoneNumber":{"type":"string","description":"Phone number of the lead","example":"+1234567890"},"mode":{"type":"string","enum":["normal","transfer_only"],"default":"normal","description":"Call mode. 'normal' for standard calls. When set to 'transfer_only', the agent will exclusively follow the provided custom instructions and only use the transfer feature from the Sophiie dashboard—no other organization data or context will be added or accessed.","example":"normal"},"custom_instructions":{"type":"string","description":"Custom instructions for the agent. Required when mode is 'transfer_only'. When in 'transfer_only' mode, the agent will ignore all other organization data and rules, using only these instructions and the transfer functionality.","example":"You are a transfer agent. Your only job is to greet the customer and transfer them to the sales team."}},"required":["name","phoneNumber"]}}}},"responses":{"200":{"description":"Call initiated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Call initiated successfully"}},"required":["message"]}}}},"400":{"description":"Bad request - Invalid input or call delivery failure","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"No virtual assistant phone found for organization","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/faqs":{"get":{"summary":"List FAQs","description":"Retrieve a paginated list of faqs. Returns FAQ data including question, answer. Results are filtered by the organization associated with the API key.","tags":["FAQs"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated FAQ data","content":{"application/json":{"schema":{"type":"object","properties":{"faqs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the FAQ","example":123},"question":{"type":"string","description":"Question of the FAQ","example":"What is the question of the FAQ?"},"answer":{"type":"string","description":"Answer of the FAQ","example":"This is the answer of the FAQ"},"isActive":{"type":"boolean","description":"Whether the FAQ is active","example":true}},"required":["id","question","answer","isActive"]},"description":"Array of FAQs"},"totalPages":{"type":"number","description":"Total number of pages available","example":5},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of FAQs","example":250}},"required":["faqs","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"post":{"summary":"Create FAQ","description":"Create a new FAQ entry. The FAQ will be associated with the organization of the API key.","tags":["FAQs"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":255,"description":"Question of the FAQ","example":"What is the question of the FAQ?"},"answer":{"type":"string","minLength":1,"description":"Answer of the FAQ","example":"This is the answer of the FAQ"},"isActive":{"type":"boolean","description":"Whether the FAQ is active","example":true}},"required":["question","answer"]}}}},"responses":{"200":{"description":"FAQ created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"faq":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the FAQ","example":123},"question":{"type":"string","description":"Question of the FAQ","example":"What is the question of the FAQ?"},"answer":{"type":"string","description":"Answer of the FAQ","example":"This is the answer of the FAQ"},"isActive":{"type":"boolean","description":"Whether the FAQ is active","example":true}},"required":["id","question","answer","isActive"]}},"required":["faq"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/faqs/{faqId}":{"put":{"summary":"Update FAQ","description":"Update an existing FAQ entry. Only FAQs belonging to the organization associated with the API key can be updated.","tags":["FAQs"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the FAQ","example":1},"required":false,"description":"The unique identifier of the FAQ","name":"faqId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":255,"description":"Question of the FAQ","example":"What is the question of the FAQ?"},"answer":{"type":"string","minLength":1,"description":"Answer of the FAQ","example":"This is the answer of the FAQ"},"isActive":{"type":"boolean","description":"Whether the FAQ is active","example":true}}}}}},"responses":{"200":{"description":"FAQ updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"faq":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the FAQ","example":123},"question":{"type":"string","description":"Question of the FAQ","example":"What is the question of the FAQ?"},"answer":{"type":"string","description":"Answer of the FAQ","example":"This is the answer of the FAQ"},"isActive":{"type":"boolean","description":"Whether the FAQ is active","example":true}},"required":["id","question","answer","isActive"]}},"required":["faq"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"FAQ not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete FAQ","description":"Delete an existing FAQ entry. Only FAQs belonging to the organization associated with the API key can be deleted. This performs a soft delete.","tags":["FAQs"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the FAQ","example":1},"required":false,"description":"The unique identifier of the FAQ","name":"faqId","in":"path"}],"responses":{"200":{"description":"FAQ deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"FAQ deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"FAQ not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/inquiries":{"get":{"summary":"List Inquiries","description":"Retrieve a paginated list of inquiries. Supports filtering by lead ID. Results are filtered by the organization associated with the API key.","tags":["Inquiries"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Filter inquiries by lead ID","example":"ld_abc123"},"required":false,"description":"Filter inquiries by lead ID","name":"leadId","in":"query"},{"schema":{"type":"string","enum":["CALL","EMAIL","CHATBOT","SMS","WEBFORM"],"description":"Filter inquiries by source type","example":"CALL"},"required":false,"description":"Filter inquiries by source type","name":"source","in":"query"},{"schema":{"type":"string","enum":["external","lead","both"],"description":"Expand additional data: 'external' for externalInquiryId, 'lead' for lead info, 'both' for both","example":"both"},"required":false,"description":"Expand additional data: 'external' for externalInquiryId, 'lead' for lead info, 'both' for both","name":"expand","in":"query"}],"responses":{"200":{"description":"Successful response with paginated inquiry data","content":{"application/json":{"schema":{"type":"object","properties":{"inquiries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"source":{"type":"string","enum":["CALL","EMAIL","CHATBOT","SMS","WEBFORM"],"description":"Source of the inquiry","example":"CALL"},"sourceId":{"type":"string","description":"ID of the associated source record (Call, ChatbotThread, MessageThread, WebformSubmission)","example":"call_abc123"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","source","sourceId","tag","summary","isFirstInquiry","isRead","leadId","createdAt"]},"description":"Array of inquiries"},"totalPages":{"type":"number","description":"Total number of pages available","example":3},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of inquiries","example":125}},"required":["inquiries","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/inquiries/{inquiryId}":{"get":{"summary":"Get Inquiry","description":"Retrieve a single inquiry with populated polymorphic source data. Results are filtered by the organization associated with the API key.","tags":["Inquiries"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier for the inquiry","example":"in_abc123"},"required":true,"description":"The unique identifier for the inquiry","name":"inquiryId","in":"path"}],"responses":{"200":{"description":"Successful response with inquiry data and expanded source data","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"source":{"type":"string","enum":["CALL"],"description":"Source type for call inquiries"},"data":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Call ID","example":"123456"},"summary":{"type":"string","description":"Summary of the call","example":"Customer inquiry about service"},"keyPoints":{"type":"array","items":{"type":"string"},"description":"Key points from the call","example":["Interested in premium service","Needs quote"]},"recordingUrl":{"type":"string","description":"URL to the call recording","example":"https://example.com/recording.mp3"},"transcripts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"number"}]},"text":{"type":"string"},"user":{"type":"string","enum":["assistant","user","transferee"]}},"required":["id","created_at","text","user"]},"description":"Call transcripts"},"direction":{"type":"string","description":"Call direction","example":"LEAD_TO_AI"},"duration":{"type":"number","description":"Call duration in seconds","example":300},"startedAt":{"type":"string","description":"Call start time (ISO 8601)","example":"2023-01-01T10:00:00.000Z"},"endedAt":{"type":"string","description":"Call end time (ISO 8601)","example":"2023-01-01T10:05:00.000Z"},"endedBy":{"type":"string","description":"Who ended the call","example":"user"}},"required":["id","summary","keyPoints","recordingUrl","transcripts","direction","duration","startedAt","endedAt","endedBy"],"description":"Call data associated with the inquiry"}},"required":["id","tag","summary","isFirstInquiry","isRead","leadId","createdAt","source","data"],"description":"Inquiry with a CALL source","title":"Call Inquiry"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"source":{"type":"string","enum":["CHATBOT"],"description":"Source type for chatbot inquiries"},"data":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Chatbot thread ID","example":"123456"},"summary":{"type":"string","description":"Summary of the chatbot conversation","example":"Customer inquiry about pricing"},"transcripts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"number"}]},"text":{"type":"string"},"user":{"type":"string","enum":["assistant","user","transferee"]}},"required":["id","created_at","text","user"]},"description":"Chatbot conversation transcripts"},"startedAt":{"type":"string","description":"Conversation start time (ISO 8601)","example":"2023-01-01T10:00:00.000Z"},"endedAt":{"type":"string","description":"Conversation end time (ISO 8601)","example":"2023-01-01T10:15:00.000Z"}},"required":["id","summary","transcripts","startedAt","endedAt"],"description":"Chatbot thread data associated with the inquiry"}},"required":["id","tag","summary","isFirstInquiry","isRead","leadId","createdAt","source","data"],"description":"Inquiry with a CHATBOT source","title":"Chatbot Inquiry"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"source":{"type":"string","enum":["WEBFORM"],"description":"Source type for webform inquiries"},"data":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Webform submission ID","example":"123456"},"summary":{"type":"string","description":"Summary of the webform submission","example":"Service inquiry form"},"submissionData":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"businessName":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"address":{"type":"object","properties":{"formattedAddress":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string","nullable":true},"lat":{"type":"string"},"lng":{"type":"string"}},"required":["formattedAddress"]},"message":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"url":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}},"required":["file","url"]}},"tradeServiceId":{"type":"number"},"preferredDate":{"type":"string"},"preferredTime":{"type":"string"}},"description":"Webform submission data"},"submittedAt":{"type":"string","description":"Submission timestamp (ISO 8601)","example":"2023-01-01T10:00:00.000Z"}},"required":["id","summary","submissionData","submittedAt"],"description":"Webform submission data associated with the inquiry"}},"required":["id","tag","summary","isFirstInquiry","isRead","leadId","createdAt","source","data"],"description":"Inquiry with a WEBFORM source","title":"Webform Inquiry"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"source":{"type":"string","enum":["SMS"],"description":"Source type for SMS inquiries"},"data":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Message thread ID","example":"123456"},"source":{"type":"string","description":"Message source","example":"SMS"},"externalId":{"type":"string","description":"External thread ID","example":"ext_123"},"isClosed":{"type":"boolean","description":"Whether the message thread is closed","example":false},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Message ID","example":"456789"},"subject":{"type":"string","nullable":true,"description":"Message subject (for emails)","example":"Re: Service inquiry"},"content":{"type":"string","description":"Message content","example":"Hello, I'm interested in your services..."},"source":{"type":"string","description":"Message source","example":"SMS"},"direction":{"type":"string","description":"Message direction","example":"INBOUND"},"sender":{"type":"string","description":"Sender contact (email/phone)","example":"+1234567890"},"senderId":{"type":"string","description":"Sender ID","example":"ld_abc123"},"senderType":{"type":"string","description":"Sender type","example":"LEAD"},"receiver":{"type":"string","description":"Receiver contact (email/phone)","example":"+0987654321"},"receiverId":{"type":"string","description":"Receiver ID","example":"SOPHIIE_AI"},"receiverType":{"type":"string","description":"Receiver type","example":"AI_AGENT"},"externalId":{"type":"string","description":"External message ID","example":"twilio_msg_123"},"sentiment":{"type":"string","nullable":true,"description":"AI-analyzed sentiment","example":"positive"},"summary":{"type":"string","nullable":true,"description":"AI-generated summary","example":"Customer expressing interest in premium services"},"keyPoints":{"type":"array","nullable":true,"items":{"type":"string"},"description":"AI-extracted key points","example":["Interested in premium plan","Needs pricing info"]},"attachments":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"url":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}},"required":["file","url"]},"description":"Message attachments"},"repliedByAI":{"type":"boolean","description":"Whether this message was replied to by AI","example":true},"createdAt":{"type":"string","description":"Message creation timestamp (ISO 8601)","example":"2023-01-01T10:00:00.000Z"}},"required":["id","subject","content","source","direction","sender","senderId","senderType","receiver","receiverId","receiverType","externalId","sentiment","summary","keyPoints","attachments","repliedByAI","createdAt"]},"description":"All messages in the thread"}},"required":["id","source","externalId","isClosed","messages"],"description":"SMS message data associated with the inquiry"}},"required":["id","tag","summary","isFirstInquiry","isRead","leadId","createdAt","source","data"],"description":"Inquiry with a SMS source","title":"SMS Inquiry"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"source":{"type":"string","enum":["EMAIL"],"description":"Source type for email inquiries"},"data":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Message thread ID","example":"123456"},"source":{"type":"string","description":"Message source","example":"SMS"},"externalId":{"type":"string","description":"External thread ID","example":"ext_123"},"isClosed":{"type":"boolean","description":"Whether the message thread is closed","example":false},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Message ID","example":"456789"},"subject":{"type":"string","nullable":true,"description":"Message subject (for emails)","example":"Re: Service inquiry"},"content":{"type":"string","description":"Message content","example":"Hello, I'm interested in your services..."},"source":{"type":"string","description":"Message source","example":"SMS"},"direction":{"type":"string","description":"Message direction","example":"INBOUND"},"sender":{"type":"string","description":"Sender contact (email/phone)","example":"+1234567890"},"senderId":{"type":"string","description":"Sender ID","example":"ld_abc123"},"senderType":{"type":"string","description":"Sender type","example":"LEAD"},"receiver":{"type":"string","description":"Receiver contact (email/phone)","example":"+0987654321"},"receiverId":{"type":"string","description":"Receiver ID","example":"SOPHIIE_AI"},"receiverType":{"type":"string","description":"Receiver type","example":"AI_AGENT"},"externalId":{"type":"string","description":"External message ID","example":"twilio_msg_123"},"sentiment":{"type":"string","nullable":true,"description":"AI-analyzed sentiment","example":"positive"},"summary":{"type":"string","nullable":true,"description":"AI-generated summary","example":"Customer expressing interest in premium services"},"keyPoints":{"type":"array","nullable":true,"items":{"type":"string"},"description":"AI-extracted key points","example":["Interested in premium plan","Needs pricing info"]},"attachments":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"url":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}},"required":["file","url"]},"description":"Message attachments"},"repliedByAI":{"type":"boolean","description":"Whether this message was replied to by AI","example":true},"createdAt":{"type":"string","description":"Message creation timestamp (ISO 8601)","example":"2023-01-01T10:00:00.000Z"}},"required":["id","subject","content","source","direction","sender","senderId","senderType","receiver","receiverId","receiverType","externalId","sentiment","summary","keyPoints","attachments","repliedByAI","createdAt"]},"description":"All messages in the thread"}},"required":["id","source","externalId","isClosed","messages"],"description":"Email message data associated with the inquiry"}},"required":["id","tag","summary","isFirstInquiry","isRead","leadId","createdAt","source","data"],"description":"Inquiry with a EMAIL source","title":"Email Inquiry"}],"description":"Inquiry with expanded polymorphic source data"}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Inquiry not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/companies/{companyId}/notes":{"get":{"summary":"List Company Notes","description":"Retrieve a paginated list of notes for a specific company. Returns note data including content, creation timestamps, and associated user information. Results are filtered by the organization associated with the API key.","tags":["Companies"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the company","example":"cmp_abc123"},"required":true,"description":"The unique identifier of the company","name":"companyId","in":"path"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated note data","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the note","example":123},"value":{"type":"string","description":"Content of the note","example":"Follow up with property manager about maintenance schedule"},"companyId":{"type":"string","description":"Associated company ID","example":"cmp_abc123"},"userId":{"type":"string","description":"User who created the note","example":"usr_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"Last update timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","value","companyId","userId","createdAt","updatedAt"]},"description":"Array of company notes"},"totalPages":{"type":"number","description":"Total number of pages available","example":3},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of notes","example":15}},"required":["notes","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/leads":{"get":{"summary":"List Leads","description":"Retrieve a paginated list of leads. Returns lead data including contact information, status, and inquiry statistics. Results are filtered by the organization associated with the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated lead data","content":{"application/json":{"schema":{"type":"object","properties":{"leads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the lead","example":"ld_abc123"},"firstName":{"type":"string","description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead","example":"+1234567890"},"suburb":{"type":"string","nullable":true,"description":"Suburb/location of the lead","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Social media information","example":{}},"status":{"type":"string","description":"Current status of the lead","example":"active"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"read":{"type":"boolean","description":"Whether the lead has been read","example":false},"lastInquiryId":{"type":"string","nullable":true,"description":"ID of the last inquiry from this lead","example":"in_abc123"},"lastInquiryDate":{"type":"string","nullable":true,"description":"Date of the last inquiry from this lead (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"unreadEmails":{"type":"number","nullable":true,"description":"Number of unread emails","example":0},"unreadCalls":{"type":"number","nullable":true,"description":"Number of unread calls","example":1},"unreadChatbotThreads":{"type":"number","nullable":true,"description":"Number of unread chatbot threads","example":0},"unreadSMS":{"type":"number","nullable":true,"description":"Number of unread SMS messages","example":0},"unreadWebformSubmissions":{"type":"number","nullable":true,"description":"Number of unread webform submissions","example":0},"hasFlaggedInquiry":{"type":"boolean","description":"Whether the lead has any flagged inquiries","example":false}},"required":["id","firstName","lastName","email","phone","suburb","businessName","socials","status","createdAt","read","lastInquiryId","lastInquiryDate","unreadEmails","unreadCalls","unreadChatbotThreads","unreadSMS","unreadWebformSubmissions","hasFlaggedInquiry"]},"description":"Array of leads"},"totalPages":{"type":"number","description":"Total number of pages available","example":5},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of leads","example":250}},"required":["leads","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"post":{"summary":"Create Lead","description":"Create a new lead entry. The lead will be associated with the organization of the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":2,"maxLength":255,"description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"format":"email","description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead","example":"+1234567890"},"suburb":{"type":"string","maxLength":255,"default":"","description":"Suburb/location of the lead (optional)","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","properties":{"instagram":{"type":"string","description":"Instagram URL","example":"https://www.instagram.com/john.doe"},"facebook":{"type":"string","description":"Facebook URL","example":"https://www.facebook.com/john.doe"}}}},"required":["firstName"]}}}},"responses":{"200":{"description":"Lead created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"lead":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the lead","example":"ld_abc123"},"firstName":{"type":"string","description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead","example":"+1234567890"},"suburb":{"type":"string","nullable":true,"description":"Suburb/location of the lead","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Social media information","example":{}},"status":{"type":"string","description":"Current status of the lead","example":"active"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","firstName","lastName","email","phone","suburb","businessName","socials","status","createdAt"]}},"required":["lead"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Conflict - Lead already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/leads/{leadId}":{"get":{"summary":"Get Lead Details","description":"Retrieve detailed information for a specific lead and address information. Results are filtered by the organization associated with the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the lead","example":"ld_abc123"},"required":true,"description":"The unique identifier of the lead","name":"leadId","in":"path"}],"responses":{"200":{"description":"Successful response with detailed lead data","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the lead","example":"ld_abc123"},"firstName":{"type":"string","description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead","example":"+1234567890"},"suburb":{"type":"string","nullable":true,"description":"Suburb/location of the lead","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Social media information","example":{}},"status":{"type":"string","description":"Current status of the lead","example":"active"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"read":{"type":"boolean","description":"Whether the lead has been read","example":false},"lastInquiryId":{"type":"string","nullable":true,"description":"ID of the last inquiry from this lead","example":"in_abc123"},"lastInquiryDate":{"type":"string","nullable":true,"description":"Date of the last inquiry from this lead (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"unreadEmails":{"type":"number","nullable":true,"description":"Number of unread emails","example":0},"unreadCalls":{"type":"number","nullable":true,"description":"Number of unread calls","example":1},"unreadChatbotThreads":{"type":"number","nullable":true,"description":"Number of unread chatbot threads","example":0},"unreadSMS":{"type":"number","nullable":true,"description":"Number of unread SMS messages","example":0},"unreadWebformSubmissions":{"type":"number","nullable":true,"description":"Number of unread webform submissions","example":0},"hasFlaggedInquiry":{"type":"boolean","description":"Whether the lead has any flagged inquiries","example":false},"defaultLeadAddress":{"type":"object","nullable":true,"properties":{"address":{"type":"object","nullable":true,"properties":{"line1":{"type":"string","nullable":true},"line2":{"type":"string","nullable":true},"suburb":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postcode":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}},"required":["line1","line2","suburb","state","postcode","country"]}},"required":["address"],"description":"Default address for the lead"},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true}},"required":["name","description"]},"description":"Tags associated with the lead"},"lastInquiry":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"tag":{"type":"string","nullable":true},"summary":{"type":"string"},"isFirstInquiry":{"type":"boolean"},"source":{"type":"string"},"isRead":{"type":"boolean"}},"required":["id","tag","summary","isFirstInquiry","source","isRead"],"description":"Last inquiry from the lead"}},"required":["id","firstName","lastName","email","phone","suburb","businessName","socials","status","createdAt","read","lastInquiryId","lastInquiryDate","unreadEmails","unreadCalls","unreadChatbotThreads","unreadSMS","unreadWebformSubmissions","hasFlaggedInquiry","defaultLeadAddress","tags","lastInquiry"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"put":{"summary":"Update Lead","description":"Update a new lead entry. The lead will be associated with the organization of the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the lead","example":"ld_abc123"},"required":true,"description":"The unique identifier of the lead","name":"leadId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":2,"maxLength":255,"description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"format":"email","description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead","example":"+1234567890"},"suburb":{"type":"string","maxLength":255,"description":"Suburb/location of the lead (optional)","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","properties":{"instagram":{"type":"string","description":"Instagram URL","example":"https://www.instagram.com/john.doe"},"facebook":{"type":"string","description":"Facebook URL","example":"https://www.facebook.com/john.doe"}}}}}}}},"responses":{"200":{"description":"Lead updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"lead":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the lead","example":"ld_abc123"},"firstName":{"type":"string","description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead","example":"+1234567890"},"suburb":{"type":"string","nullable":true,"description":"Suburb/location of the lead","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Social media information","example":{}},"status":{"type":"string","description":"Current status of the lead","example":"active"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","firstName","lastName","email","phone","suburb","businessName","socials","status","createdAt"]}},"required":["lead"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Conflict - Lead already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete Lead","description":"Soft delete a lead and related entities, sync deletion to external systems, and emit relevant webhooks. Only leads belonging to the organization associated with the API key can be deleted.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the lead","example":"ld_abc123"},"required":true,"description":"The unique identifier of the lead","name":"leadId","in":"path"}],"responses":{"200":{"description":"Lead deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Lead deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/leads/{leadId}/notes":{"get":{"summary":"List Lead Notes","description":"Retrieve a paginated list of notes for a specific lead. Returns note data including content, creation timestamps, and associated user information. Results are filtered by the organization associated with the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the lead","example":"ld_abc123"},"required":true,"description":"The unique identifier of the lead","name":"leadId","in":"path"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated note data","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the note","example":123},"value":{"type":"string","description":"Content of the note","example":"Customer mentioned they need installation next week"},"appointmentId":{"type":"string","nullable":true,"description":"Associated appointment ID if linked to an appointment","example":"apt_abc123"},"leadId":{"type":"string","description":"Associated lead ID","example":"ld_abc123"},"userId":{"type":"string","description":"User who created the note","example":"usr_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"Last update timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","value","appointmentId","leadId","userId","createdAt","updatedAt"]},"description":"Array of notes"},"totalPages":{"type":"number","description":"Total number of pages available","example":3},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of notes","example":15}},"required":["notes","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/leads/{leadId}/activities":{"get":{"summary":"List Lead Activities","description":"Retrieve a paginated list of activities for a specific lead. Returns activity data including event types, timestamps, and associated data. Results are filtered by the organization associated with the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the lead","example":"ld_abc123"},"required":true,"description":"The unique identifier of the lead","name":"leadId","in":"path"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated activity data","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the activity","example":456},"event":{"type":"string","description":"Type of activity event","example":"LEAD_CREATED"},"data":{"type":"string","nullable":true,"description":"Additional data associated with the activity","example":"Status changed from pending to active"},"referenceId":{"type":"string","nullable":true,"description":"Reference ID to related entity (appointment, note, etc.)","example":"apt_abc123"},"userId":{"type":"string","nullable":true,"description":"User who triggered the activity (null if system-generated)","example":"usr_abc123"},"leadId":{"type":"string","description":"Associated lead ID","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","event","data","referenceId","userId","leadId","createdAt"]},"description":"Array of activities"},"totalPages":{"type":"number","description":"Total number of pages available","example":5},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of activities","example":42}},"required":["activities","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/members":{"get":{"summary":"List Members","description":"Retrieve a paginated list of members. Results are filtered by the organization associated with the API key.","tags":["Members"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated member data","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the member","example":"usr_123"},"role":{"type":"string","enum":["OWNER","ADMIN","USER"],"description":"Role of the member","example":"OWNER"},"firstName":{"type":"string","nullable":true,"description":"First name of the member","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the member","example":"Doe"},"email":{"type":"string","nullable":true,"description":"Email of the member","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the member","example":"+1234567890"},"isDisabled":{"type":"boolean","description":"Whether the membership is disabled","example":false},"responsibility":{"type":"string","nullable":true,"description":"Member's responsibility in the organization","example":"Manages daily operations and customer service"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","role","firstName","lastName","email","phone","isDisabled","responsibility","createdAt"]},"description":"Array of members"},"totalPages":{"type":"number","description":"Total number of pages available","example":5},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of members","example":250}},"required":["members","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/organization":{"get":{"summary":"Get Organization Details","description":"Retrieve detailed information about the organization associated with the API key. Returns organization settings, contact information, and configuration details.","tags":["Organization"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response with organization details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the organization","example":"org_abc123"},"name":{"type":"string","description":"Name of the organization","example":"Acme Plumbing Services"},"businessPhone":{"type":"string","nullable":true,"description":"Business phone number","example":"+1234567890"},"website":{"type":"string","nullable":true,"description":"Organization website URL","example":"https://acmeplumbing.com"},"socials":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Social media links and information","example":{"facebook":"acmeplumbing","instagram":"acme_plumbing"}},"timeZone":{"type":"string","description":"Organization timezone","example":"Australia/Sydney"},"country":{"type":"string","description":"Country code","example":"AU"},"currency":{"type":"string","description":"Currency code","example":"AUD"},"timeFormat":{"type":"number","description":"Time format preference (12 or 24)","example":12},"weekStart":{"type":"string","description":"First day of the week","example":"Monday"}},"required":["id","name","businessPhone","website","socials","timeZone","country","currency","timeFormat","weekStart"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/organization/availability":{"get":{"summary":"Get Organization Availability","description":"Retrieve the availability schedules for the organization. Returns schedule information including available time slots, timezone, and day configurations for business hours.","tags":["Organization"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response with organization availability schedules","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Schedule ID","example":1},"name":{"type":"string","description":"Schedule name","example":"Business Hours"},"timeZone":{"type":"string","nullable":true,"description":"Schedule timezone (inherits from organization if null)","example":"Australia/Sydney"},"orgId":{"type":"string","description":"Organization ID","example":"org_abc123"},"availability":{"type":"array","items":{"type":"object","properties":{"days":{"type":"array","items":{"type":"string"},"description":"Days of the week for this availability slot","example":["Monday","Tuesday","Wednesday"]},"startTime":{"type":"string","description":"Start time in HH:mm format","example":"09:00"},"endTime":{"type":"string","description":"End time in HH:mm format","example":"17:00"}},"required":["days","startTime","endTime"]},"description":"Available time slots"}},"required":["id","name","timeZone","orgId","availability"]},"description":"Organization availability schedules"}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Organization or availability not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/organization/members":{"get":{"summary":"List Organization Members","description":"Retrieve a paginated list of organization members. Excludes pending invitations (users without associated user accounts). Returns member information including roles, contact details, and user associations.","tags":["Organization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated member data","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the membership","example":123},"role":{"type":"string","description":"Role of the member in the organization","example":"ADMIN"},"firstName":{"type":"string","nullable":true,"description":"First name of the member","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the member","example":"Doe"},"position":{"type":"string","nullable":true,"description":"Position/title of the member","example":"Operations Manager"},"avatarImg":{"type":"string","nullable":true,"description":"Avatar image URL or asset key","example":"https://example.com/avatar.jpg"},"isDisabled":{"type":"boolean","description":"Whether the membership is disabled","example":false},"responsibility":{"type":"string","nullable":true,"description":"Member's responsibility in the organization","example":"Manages daily operations and customer service"},"user":{"type":"object","nullable":true,"properties":{"email":{"type":"string"}},"required":["email"],"description":"Associated user information","example":{"email":"john.doe@acme.com"}}},"required":["id","role","firstName","lastName","position","avatarImg","isDisabled","responsibility","user"]},"description":"Array of organization members (excludes pending invitations)"},"totalPages":{"type":"number","description":"Total number of pages available","example":2},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of members","example":8}},"required":["members","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/organization/services":{"get":{"summary":"List Organization Services","description":"Retrieve all services for the organization, grouped by trade categories. Returns service information including names, descriptions, durations, and follow-up questions organized by their respective categories.","tags":["Organization"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response with services grouped by categories","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the category","example":1},"name":{"type":"string","description":"Name of the category","example":"Kitchen Services"},"type":{"type":"string","description":"Type of the category","example":"SERVICE"},"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the service","example":123},"name":{"type":"string","description":"Name of the service","example":"Kitchen Installation"},"description":{"type":"string","description":"Description of the service","example":"Complete kitchen renovation and installation service"},"duration":{"type":"number","nullable":true,"description":"Service duration in minutes","example":180},"followUpQuestions":{"type":"array","items":{"type":"string"},"description":"Follow-up questions for this service","example":["What type of countertops do you prefer?","Do you need electrical work?"]},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":1},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"isActive":{"type":"boolean","description":"Whether the service is active","example":true}},"required":["id","name","description","duration","followUpQuestions","tradeCategoryId","createdAt","isActive"]},"description":"Services in this category"}},"required":["id","name","type","services"]},"description":"Array of service categories with their associated services"},"totalCategories":{"type":"number","description":"Total number of categories","example":5},"totalServices":{"type":"number","description":"Total number of services across all categories","example":23}},"required":["categories","totalCategories","totalServices"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/organization/products":{"get":{"summary":"List Organization Products","description":"Retrieve all products for the organization, grouped by trade categories. Returns product information including names, descriptions, and pricing organized by their respective categories.","tags":["Organization"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response with products grouped by categories","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the category","example":2},"name":{"type":"string","description":"Name of the category","example":"Kitchen Materials"},"type":{"type":"string","description":"Type of the category","example":"PRODUCT"},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the product","example":456},"name":{"type":"string","description":"Name of the product","example":"Premium Granite Countertop"},"description":{"type":"string","description":"Description of the product","example":"High-quality granite countertop with polished finish"},"price":{"type":"number","description":"Product price","example":299.99},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":2},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"isActive":{"type":"boolean","description":"Whether the product is active","example":true}},"required":["id","name","description","price","tradeCategoryId","createdAt","isActive"]},"description":"Products in this category"}},"required":["id","name","type","products"]},"description":"Array of product categories with their associated products"},"totalCategories":{"type":"number","description":"Total number of categories","example":3},"totalProducts":{"type":"number","description":"Total number of products across all categories","example":47}},"required":["categories","totalCategories","totalProducts"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/policies":{"get":{"summary":"List Policies","description":"Retrieve a paginated list of policies. Returns policy data including title, content, and summary. Results are filtered by the organization associated with the API key.","tags":["Policies"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated policy data","content":{"application/json":{"schema":{"type":"object","properties":{"policies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the policy","example":123},"title":{"type":"string","description":"Title of the policy","example":"Privacy Policy"},"content":{"type":"string","description":"Content of the policy","example":"This is the content of the policy"},"isActive":{"type":"boolean","description":"Whether the policy is active","example":true}},"required":["id","title","content","isActive"]},"description":"Array of policies"},"totalPages":{"type":"number","description":"Total number of pages available","example":5},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of policies","example":250}},"required":["policies","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"post":{"summary":"Create Policy","description":"Create a new policy entry. The policy will be associated with the organization of the API key.","tags":["Policies"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":2,"maxLength":255,"description":"Title of the policy","example":"Privacy Policy"},"content":{"type":"string","minLength":2,"description":"Content of the policy","example":"This is the content of the policy"},"isActive":{"type":"boolean","description":"Whether the policy is active","example":true}},"required":["title","content"]}}}},"responses":{"200":{"description":"Policy created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the policy","example":123},"title":{"type":"string","description":"Title of the policy","example":"Privacy Policy"},"content":{"type":"string","description":"Content of the policy","example":"This is the content of the policy"},"isActive":{"type":"boolean","description":"Whether the policy is active","example":true}},"required":["id","title","content","isActive"]}},"required":["policy"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/policies/{policyId}":{"put":{"summary":"Update Policy","description":"Update an existing policy entry. Only policies belonging to the organization associated with the API key can be updated.","tags":["Policies"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the policy","example":1},"required":false,"description":"The unique identifier of the policy","name":"policyId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":2,"maxLength":255,"description":"Title of the policy","example":"Privacy Policy"},"content":{"type":"string","minLength":2,"description":"Content of the policy","example":"This is the content of the policy"},"isActive":{"type":"boolean","description":"Whether the policy is active","example":true}}}}}},"responses":{"200":{"description":"Policy updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the policy","example":123},"title":{"type":"string","description":"Title of the policy","example":"Privacy Policy"},"content":{"type":"string","description":"Content of the policy","example":"This is the content of the policy"},"isActive":{"type":"boolean","description":"Whether the policy is active","example":true}},"required":["id","title","content","isActive"]}},"required":["policy"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete Policy","description":"Delete an existing policy entry. Only policies belonging to the organization associated with the API key can be deleted. This performs a soft delete.","tags":["Policies"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the policy","example":1},"required":false,"description":"The unique identifier of the policy","name":"policyId","in":"path"}],"responses":{"200":{"description":"Policy deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Policy deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/scenarios":{"get":{"summary":"List Scenarios","description":"Retrieve a paginated list of scenarios. Returns scenario data including name, prompt, response, questions, and outcome. Results are filtered by the organization associated with the API key.","tags":["Scenarios"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated scenario data","content":{"application/json":{"schema":{"type":"object","properties":{"scenarios":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the scenario","example":42},"name":{"type":"string","description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","description":"The prompt / instructions that describe when and how this scenario should be triggered","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","description":"The response template the agent should follow for this scenario","example":"I would be happy to help you with pricing information. Let me walk you through our options."},"isActive":{"type":"boolean","nullable":true,"description":"Whether the scenario is active","example":true},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured set of questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Defines the final outcome after completing the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID this scenario is linked to","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the scenario was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the scenario was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","name","prompt","response","isActive","questions","outcome","tradeServiceId","createdAt","updatedAt"]},"description":"Array of scenarios"},"totalPages":{"type":"number","description":"Total number of pages available","example":3},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of scenarios","example":25}},"required":["scenarios","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"post":{"summary":"Create Scenario","description":"Create a new scenario. The scenario will be associated with the organization of the API key.","tags":["Scenarios"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","minLength":1,"description":"The prompt / instructions for the scenario","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","minLength":1,"description":"The response template for the scenario","example":"I would be happy to help you with pricing."},"isActive":{"type":"boolean","description":"Whether the scenario is active (defaults to true)","example":true},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured questions with answer options and follow-ups"},"outcome":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["transferCall"]},"transferId":{"type":"number","description":"The transfer ID linking to the transfer table","example":7},"method":{"type":"string","enum":["WARM","COLD"],"description":"Transfer method: WARM (with summary) or COLD (direct)","example":"WARM"}},"required":["type","transferId","method"],"title":"TransferCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendSMS"]},"content":{"type":"string","description":"SMS content to send","example":"Thank you for calling! Here is the information you requested."}},"required":["type","content"],"title":"SendSMSOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendEmail"]},"subject":{"type":"string","description":"Email subject line","example":"Follow-up from your call"},"content":{"type":"string","description":"Email body content (HTML supported)","example":"<p>Thank you for reaching out.</p>"},"attachments":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"File URL"},"name":{"type":"string","description":"File name"},"type":{"type":"string","description":"MIME type"}},"required":["url","name","type"]},"description":"Optional file attachments"}},"required":["type","subject","content"],"title":"SendEmailOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["continueCall"]}},"required":["type"],"title":"ContinueCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["booking"]},"collect":{"type":"object","properties":{"email":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Email collection settings"},"address":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Address collection settings"}},"description":"Fields to collect during booking"}},"required":["type","collect"],"title":"BookingOutcome"}],"description":"Outcome configuration for the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID to link this scenario to","example":null}},"required":["name","prompt","response"]}}}},"responses":{"200":{"description":"Scenario created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the scenario","example":42},"name":{"type":"string","description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","description":"The prompt / instructions that describe when and how this scenario should be triggered","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","description":"The response template the agent should follow for this scenario","example":"I would be happy to help you with pricing information. Let me walk you through our options."},"isActive":{"type":"boolean","nullable":true,"description":"Whether the scenario is active","example":true},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured set of questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Defines the final outcome after completing the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID this scenario is linked to","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the scenario was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the scenario was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","name","prompt","response","isActive","questions","outcome","tradeServiceId","createdAt","updatedAt"]}},"required":["scenario"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Scenario with the same name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/scenarios/{scenarioId}":{"get":{"summary":"Get Scenario","description":"Retrieve a single scenario by ID, including questions and outcome. Only scenarios belonging to the organization associated with the API key can be retrieved.","tags":["Scenarios"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the scenario","example":42},"required":false,"description":"The unique identifier of the scenario","name":"scenarioId","in":"path"}],"responses":{"200":{"description":"Successful response with scenario data","content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the scenario","example":42},"name":{"type":"string","description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","description":"The prompt / instructions that describe when and how this scenario should be triggered","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","description":"The response template the agent should follow for this scenario","example":"I would be happy to help you with pricing information. Let me walk you through our options."},"isActive":{"type":"boolean","nullable":true,"description":"Whether the scenario is active","example":true},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured set of questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Defines the final outcome after completing the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID this scenario is linked to","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the scenario was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the scenario was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","name","prompt","response","isActive","questions","outcome","tradeServiceId","createdAt","updatedAt"]}},"required":["scenario"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Scenario not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"put":{"summary":"Update Scenario","description":"Update an existing scenario. Only scenarios belonging to the organization associated with the API key can be updated.","tags":["Scenarios"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the scenario","example":42},"required":false,"description":"The unique identifier of the scenario","name":"scenarioId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","minLength":1,"description":"The prompt / instructions for the scenario","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","minLength":1,"description":"The response template for the scenario","example":"I would be happy to help you with pricing."},"isActive":{"type":"boolean","description":"Whether the scenario is active","example":true},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured questions with answer options and follow-ups"},"outcome":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["transferCall"]},"transferId":{"type":"number","description":"The transfer ID linking to the transfer table","example":7},"method":{"type":"string","enum":["WARM","COLD"],"description":"Transfer method: WARM (with summary) or COLD (direct)","example":"WARM"}},"required":["type","transferId","method"],"title":"TransferCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendSMS"]},"content":{"type":"string","description":"SMS content to send","example":"Thank you for calling! Here is the information you requested."}},"required":["type","content"],"title":"SendSMSOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendEmail"]},"subject":{"type":"string","description":"Email subject line","example":"Follow-up from your call"},"content":{"type":"string","description":"Email body content (HTML supported)","example":"<p>Thank you for reaching out.</p>"},"attachments":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"File URL"},"name":{"type":"string","description":"File name"},"type":{"type":"string","description":"MIME type"}},"required":["url","name","type"]},"description":"Optional file attachments"}},"required":["type","subject","content"],"title":"SendEmailOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["continueCall"]}},"required":["type"],"title":"ContinueCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["booking"]},"collect":{"type":"object","properties":{"email":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Email collection settings"},"address":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Address collection settings"}},"description":"Fields to collect during booking"}},"required":["type","collect"],"title":"BookingOutcome"}],"description":"Outcome configuration for the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID to link this scenario to","example":null}}}}}},"responses":{"200":{"description":"Scenario updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the scenario","example":42},"name":{"type":"string","description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","description":"The prompt / instructions that describe when and how this scenario should be triggered","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","description":"The response template the agent should follow for this scenario","example":"I would be happy to help you with pricing information. Let me walk you through our options."},"isActive":{"type":"boolean","nullable":true,"description":"Whether the scenario is active","example":true},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured set of questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Defines the final outcome after completing the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID this scenario is linked to","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the scenario was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the scenario was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","name","prompt","response","isActive","questions","outcome","tradeServiceId","createdAt","updatedAt"]}},"required":["scenario"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Scenario not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Scenario with the same name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete Scenario","description":"Delete an existing scenario. Only scenarios belonging to the organization associated with the API key can be deleted. This performs a soft delete.","tags":["Scenarios"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the scenario","example":42},"required":false,"description":"The unique identifier of the scenario","name":"scenarioId","in":"path"}],"responses":{"200":{"description":"Scenario deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Scenario deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Scenario not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/sms":{"post":{"summary":"Send SMS","description":"Send an SMS message to a lead. The SMS will be associated with the organization of the API key. If messageThreadId is not provided, a new message thread and inquiry will be created.","tags":["SMS"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"Unique identifier for the user","example":"usr_abc123"},"leadId":{"type":"string","description":"Unique identifier for the lead","example":"ld_abc123"},"message":{"type":"string","description":"SMS message content (required for plain SMS, optional for MMS with mediaUrls)","example":"How are you?"},"messageThreadId":{"type":"number","description":"Optional message thread ID to continue an existing conversation","example":12345},"mediaUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":10,"description":"Optional array of publicly accessible HTTPS URLs for MMS media attachments (max 10, total 5MB)","example":["https://example.com/photo.jpg"]}},"required":["userId","leadId"]}}}},"responses":{"200":{"description":"SMS sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Message sent successfully"}},"required":["message"]}}}},"400":{"description":"Bad request - Invalid input or SMS delivery failure","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/transfers":{"get":{"summary":"List Transfers","description":"Retrieve a paginated list of transfer rules. Returns transfer data including label, method, destination, conditions, and settings. Results are filtered by the organization associated with the API key.","tags":["Transfers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated transfer data","content":{"application/json":{"schema":{"type":"object","properties":{"transfers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the transfer","example":7},"label":{"type":"string","minLength":2,"maxLength":255,"description":"Label for the transfer rule, so that you can identify it","example":"Sales Department Transfer"},"name":{"type":"string","nullable":true,"description":"Display name of the phone transfer destination. Only set when destinationType is PHONE; otherwise null.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method — COLD (direct pass) or WARM (with summary to transferee)","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination — a department, an individual member, or a phone number","example":"DEPARTMENT"},"destination":{"type":"string","description":"Destination identifier. Department ID (dep_*), member ID (numeric), phone (tel:*), or SIP URI (sip:*)","example":"dep_sales_01"},"conditions":{"type":"string","description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message (null for cold transfers)","example":"Customer {name} is calling about {topic}. Key details: {summary}."},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario this transfer is linked to (null if standalone)","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the transfer was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the transfer was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","label","name","method","destinationType","destination","conditions","summaryFormat","settings","isEnabled","scenarioId","createdAt","updatedAt"]},"description":"Array of transfers"},"totalPages":{"type":"number","description":"Total number of pages available","example":2},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of transfers","example":15}},"required":["transfers","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"post":{"summary":"Create Transfer","description":"Create a new transfer rule. The transfer will be associated with the organization of the API key.","tags":["Transfers"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":255,"description":"Label for the transfer rule","example":"Sales Department Transfer"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Display name of the phone transfer destination. Required when destinationType is PHONE; omit when destinationType is DEPARTMENT or MEMBER.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination","example":"DEPARTMENT"},"destination":{"type":"string","minLength":1,"maxLength":255,"description":"Destination identifier. Department ID (dep_*), member ID (numeric), phone (tel:*), or SIP URI (sip:*)","example":"dep_sales_01"},"conditions":{"type":"string","minLength":1,"description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message (null for cold transfers)","example":null},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled (defaults to true)","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario to link this transfer to","example":null}},"required":["label","method","destinationType","destination","conditions"]}}}},"responses":{"200":{"description":"Transfer created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"transfer":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the transfer","example":7},"label":{"type":"string","minLength":2,"maxLength":255,"description":"Label for the transfer rule, so that you can identify it","example":"Sales Department Transfer"},"name":{"type":"string","nullable":true,"description":"Display name of the phone transfer destination. Only set when destinationType is PHONE; otherwise null.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method — COLD (direct pass) or WARM (with summary to transferee)","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination — a department, an individual member, or a phone number","example":"DEPARTMENT"},"destination":{"type":"string","description":"Destination identifier. Department ID (dep_*), member ID (numeric), phone (tel:*), or SIP URI (sip:*)","example":"dep_sales_01"},"conditions":{"type":"string","description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message (null for cold transfers)","example":"Customer {name} is calling about {topic}. Key details: {summary}."},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario this transfer is linked to (null if standalone)","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the transfer was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the transfer was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","label","name","method","destinationType","destination","conditions","summaryFormat","settings","isEnabled","scenarioId","createdAt","updatedAt"]}},"required":["transfer"]}}}},"400":{"description":"Invalid or inaccessible scenario","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Transfer with the same label already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/transfers/{transferId}":{"get":{"summary":"Get Transfer","description":"Retrieve a single transfer rule by ID. Only transfers belonging to the organization associated with the API key can be retrieved.","tags":["Transfers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the transfer","example":7},"required":false,"description":"The unique identifier of the transfer","name":"transferId","in":"path"}],"responses":{"200":{"description":"Successful response with transfer data","content":{"application/json":{"schema":{"type":"object","properties":{"transfer":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the transfer","example":7},"label":{"type":"string","minLength":2,"maxLength":255,"description":"Label for the transfer rule, so that you can identify it","example":"Sales Department Transfer"},"name":{"type":"string","nullable":true,"description":"Display name of the phone transfer destination. Only set when destinationType is PHONE; otherwise null.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method — COLD (direct pass) or WARM (with summary to transferee)","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination — a department, an individual member, or a phone number","example":"DEPARTMENT"},"destination":{"type":"string","description":"Destination identifier. Department ID (dep_*), member ID (numeric), phone (tel:*), or SIP URI (sip:*)","example":"dep_sales_01"},"conditions":{"type":"string","description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message (null for cold transfers)","example":"Customer {name} is calling about {topic}. Key details: {summary}."},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario this transfer is linked to (null if standalone)","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the transfer was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the transfer was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","label","name","method","destinationType","destination","conditions","summaryFormat","settings","isEnabled","scenarioId","createdAt","updatedAt"]}},"required":["transfer"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Transfer not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"put":{"summary":"Update Transfer","description":"Update an existing transfer rule. Only transfers belonging to the organization associated with the API key can be updated.","tags":["Transfers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the transfer","example":7},"required":false,"description":"The unique identifier of the transfer","name":"transferId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":255,"description":"Label for the transfer rule","example":"Sales Department Transfer"},"name":{"type":"string","nullable":true,"maxLength":255,"description":"Display name of the phone transfer destination. Only used when destinationType is PHONE; set to null or omit for DEPARTMENT or MEMBER.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination","example":"DEPARTMENT"},"destination":{"type":"string","minLength":1,"maxLength":255,"description":"Destination identifier","example":"dep_sales_01"},"conditions":{"type":"string","minLength":1,"description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message","example":null},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario to link this transfer to","example":null}}}}}},"responses":{"200":{"description":"Transfer updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"transfer":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the transfer","example":7},"label":{"type":"string","minLength":2,"maxLength":255,"description":"Label for the transfer rule, so that you can identify it","example":"Sales Department Transfer"},"name":{"type":"string","nullable":true,"description":"Display name of the phone transfer destination. Only set when destinationType is PHONE; otherwise null.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method — COLD (direct pass) or WARM (with summary to transferee)","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination — a department, an individual member, or a phone number","example":"DEPARTMENT"},"destination":{"type":"string","description":"Destination identifier. Department ID (dep_*), member ID (numeric), phone (tel:*), or SIP URI (sip:*)","example":"dep_sales_01"},"conditions":{"type":"string","description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message (null for cold transfers)","example":"Customer {name} is calling about {topic}. Key details: {summary}."},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario this transfer is linked to (null if standalone)","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the transfer was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the transfer was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","label","name","method","destinationType","destination","conditions","summaryFormat","settings","isEnabled","scenarioId","createdAt","updatedAt"]}},"required":["transfer"]}}}},"400":{"description":"Invalid or inaccessible scenario","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Transfer not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Transfer with the same label already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete Transfer","description":"Delete an existing transfer rule. Only transfers belonging to the organization associated with the API key can be deleted. This performs a soft delete.","tags":["Transfers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the transfer","example":7},"required":false,"description":"The unique identifier of the transfer","name":"transferId","in":"path"}],"responses":{"200":{"description":"Transfer deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Transfer deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Transfer not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}}}}